@sonordev/contracts 1.0.0

package/dist/seo-pages.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// src/contracts/sites-normalize.ts
+function normalizeSiteHost(site) {
+  if (!site || typeof site !== "string") return null;
+  let s = site.trim().toLowerCase();
+  if (!s) return null;
+  s = s.replace(/^https?:\/\//, "");
+  const slash = s.indexOf("/");
+  if (slash >= 0) s = s.slice(0, slash);
+  const colon = s.indexOf(":");
+  if (colon >= 0) s = s.slice(0, colon);
+  s = s.replace(/\.+$/, "");
+  return s || null;
+}
+
+// src/contracts/sites.ts
+function stripWww(host) {
+  return host.startsWith("www.") ? host.slice(4) : host;
+}
+function sameSite(a, b) {
+  if (!a || !b) return false;
+  return stripWww(a) === stripWww(b);
+}
+
+// src/contracts/seo-pages.ts
+var SEO_PAGES_CONTRACT_VERSION = 1;
+var LIVE_SEO_PAGE_FILTER = "status.is.null,status.eq.active";
+function pickSeoPageRow(rows, opts = {}) {
+  if (!rows.length) return null;
+  if (rows.length === 1) return rows[0];
+  const wanted = normalizeSiteHost(opts.site);
+  if (wanted) {
+    const exact = rows.find((r) => sameSite(r.site, wanted));
+    if (exact) return exact;
+  }
+  const unattributed = rows.find((r) => !r.site);
+  if (unattributed) return unattributed;
+  const primary = normalizeSiteHost(opts.primaryHost);
+  if (primary) {
+    const main = rows.find((r) => sameSite(r.site, primary));
+    if (main) return main;
+  }
+  return [...rows].sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""))[0];
+}
+function matchSitemapEntryRow(candidates, site, primaryHost) {
+  if (!candidates.length) return null;
+  if (site) {
+    return candidates.find((r) => sameSite(r.site, site)) ?? candidates.find((r) => !r.site) ?? null;
+  }
+  return pickSeoPageRow(candidates, { primaryHost });
+}
+function scopeSeoPagesToSite(rows, site, primaryHost) {
+  const wanted = normalizeSiteHost(site);
+  const host = normalizeSiteHost(primaryHost);
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const path = row.path ?? "";
+    const key = path.replace(/\/$/, "") || path;
+    const bucket = groups.get(key);
+    if (bucket) bucket.push(row);
+    else groups.set(key, [row]);
+  }
+  const scoped = [];
+  for (const candidates of groups.values()) {
+    const picked = matchSitemapEntryRow(candidates, wanted, host);
+    if (picked) scoped.push(picked);
+  }
+  return scoped;
+}
+var SEO_PAGE_ROW_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/seo-page-row.v1.json",
+  title: "SeoPageRowLike",
+  description: "The subset of an seo_pages row that determines per-site resolution.",
+  type: "object",
+  properties: {
+    site: {
+      description: "Normalized sub-site host, or null for a project-wide row.",
+      type: ["string", "null"]
+    },
+    updated_at: {
+      description: "ISO 8601 timestamp; ties in resolution break toward the most recent.",
+      type: ["string", "null"]
+    }
+  },
+  additionalProperties: true
+};
+
+exports.LIVE_SEO_PAGE_FILTER = LIVE_SEO_PAGE_FILTER;
+exports.SEO_PAGES_CONTRACT_VERSION = SEO_PAGES_CONTRACT_VERSION;
+exports.SEO_PAGE_ROW_JSON_SCHEMA = SEO_PAGE_ROW_JSON_SCHEMA;
+exports.matchSitemapEntryRow = matchSitemapEntryRow;
+exports.pickSeoPageRow = pickSeoPageRow;
+exports.scopeSeoPagesToSite = scopeSeoPagesToSite;

package/dist/seo-pages.mjs

@@ -0,0 +1,88 @@
+// src/contracts/sites-normalize.ts
+function normalizeSiteHost(site) {
+  if (!site || typeof site !== "string") return null;
+  let s = site.trim().toLowerCase();
+  if (!s) return null;
+  s = s.replace(/^https?:\/\//, "");
+  const slash = s.indexOf("/");
+  if (slash >= 0) s = s.slice(0, slash);
+  const colon = s.indexOf(":");
+  if (colon >= 0) s = s.slice(0, colon);
+  s = s.replace(/\.+$/, "");
+  return s || null;
+}
+
+// src/contracts/sites.ts
+function stripWww(host) {
+  return host.startsWith("www.") ? host.slice(4) : host;
+}
+function sameSite(a, b) {
+  if (!a || !b) return false;
+  return stripWww(a) === stripWww(b);
+}
+
+// src/contracts/seo-pages.ts
+var SEO_PAGES_CONTRACT_VERSION = 1;
+var LIVE_SEO_PAGE_FILTER = "status.is.null,status.eq.active";
+function pickSeoPageRow(rows, opts = {}) {
+  if (!rows.length) return null;
+  if (rows.length === 1) return rows[0];
+  const wanted = normalizeSiteHost(opts.site);
+  if (wanted) {
+    const exact = rows.find((r) => sameSite(r.site, wanted));
+    if (exact) return exact;
+  }
+  const unattributed = rows.find((r) => !r.site);
+  if (unattributed) return unattributed;
+  const primary = normalizeSiteHost(opts.primaryHost);
+  if (primary) {
+    const main = rows.find((r) => sameSite(r.site, primary));
+    if (main) return main;
+  }
+  return [...rows].sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""))[0];
+}
+function matchSitemapEntryRow(candidates, site, primaryHost) {
+  if (!candidates.length) return null;
+  if (site) {
+    return candidates.find((r) => sameSite(r.site, site)) ?? candidates.find((r) => !r.site) ?? null;
+  }
+  return pickSeoPageRow(candidates, { primaryHost });
+}
+function scopeSeoPagesToSite(rows, site, primaryHost) {
+  const wanted = normalizeSiteHost(site);
+  const host = normalizeSiteHost(primaryHost);
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const path = row.path ?? "";
+    const key = path.replace(/\/$/, "") || path;
+    const bucket = groups.get(key);
+    if (bucket) bucket.push(row);
+    else groups.set(key, [row]);
+  }
+  const scoped = [];
+  for (const candidates of groups.values()) {
+    const picked = matchSitemapEntryRow(candidates, wanted, host);
+    if (picked) scoped.push(picked);
+  }
+  return scoped;
+}
+var SEO_PAGE_ROW_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/seo-page-row.v1.json",
+  title: "SeoPageRowLike",
+  description: "The subset of an seo_pages row that determines per-site resolution.",
+  type: "object",
+  properties: {
+    site: {
+      description: "Normalized sub-site host, or null for a project-wide row.",
+      type: ["string", "null"]
+    },
+    updated_at: {
+      description: "ISO 8601 timestamp; ties in resolution break toward the most recent.",
+      type: ["string", "null"]
+    }
+  },
+  additionalProperties: true
+};
+
+export { LIVE_SEO_PAGE_FILTER, SEO_PAGES_CONTRACT_VERSION, SEO_PAGE_ROW_JSON_SCHEMA, matchSitemapEntryRow, pickSeoPageRow, scopeSeoPagesToSite };

package/dist/sites-normalize.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @sonordev/contracts/sites — normalizeSiteHost (leaf module)
+ *
+ * Deliberately its own file, not part of `./sites`, so browser code can pull
+ * in the normalizer WITHOUT the rest of the contract surface.
+ *
+ * `publishCredential` (which every client entry that publishes a credential
+ * imports) needs exactly this one function. When it lived in `./contract`, the
+ * bundler emitted that whole module as one shared chunk — `SITE_HOST_JSON_SCHEMA`,
+ * `SITE_HOST_CONTRACT_VERSION`, `stripWww`, `sameSite`, `hostFromUrl`,
+ * `isNormalizedSiteHost` and all — into `client`, `layout/client` and every
+ * other entry that touched it. That was ~750B gzipped of agent-facing contract
+ * metadata shipped to browsers for a 14-line string normalizer, and it is what
+ * 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`).
+ *
+ * Pure string logic only (no Node built-ins) so it is safe in the browser.
+ */
+/**
+ * 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`
+ *
+ * Lowercases, strips protocol, keeps host only (drops path + query), strips
+ * port (rollups span dev/prod) and the FQDN root dot. Returns null for
+ * empty/non-string input.
+ * Note: `www.` is intentionally preserved here — use `sameSite`/`stripWww`
+ * for www-insensitive equality.
+ */
+export declare function normalizeSiteHost(site?: string | null): string | null;

package/dist/sites.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @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.
+ *
+ * Pure string logic only (no Node built-ins) so it is safe in the browser:
+ * site-kit itself normalizes `__SITE_KIT_SITE__` with `normalizeSiteHost`.
+ */
+/** Bump on breaking changes to the normalized host shape. */
+export declare const SITE_HOST_CONTRACT_VERSION: 1;
+/**
+ * The normalizer itself lives in `./sites-normalize`, a leaf module, so browser code
+ * (`shared/publishCredential`) can import it without dragging this whole module
+ * — JSON schema included — into client bundles. Re-exported here so the public
+ * contract surface is unchanged.
+ */
+export { normalizeSiteHost } from './sites-normalize';
+/** Strip a leading `www.` from a host ("www.tps.com" → "tps.com"). */
+export declare function stripWww(host: string): string;
+/**
+ * www-insensitive sub-site host equality — `www.a.com` and `a.com` are the
+ * same site. Operands are expected already-normalized (lowercase host);
+ * returns false if either side is missing.
+ */
+export declare function sameSite(a: string | null | undefined, b: string | null | undefined): boolean;
+/**
+ * Host of a full URL ("https://ohiopowerstudies.com/x" → "ohiopowerstudies.com"),
+ * null for site-relative paths ("/services") and unparseable input.
+ */
+export declare function hostFromUrl(value: string | null | undefined): string | null;
+/** True when `value` is a non-empty normalized host (lowercase, no protocol/path/port). */
+export declare function isNormalizedSiteHost(value: unknown): value is string;
+/**
+ * Agent-native contract: JSON Schema for a normalized `site` value, so services
+ * and agents can validate the dimension mechanically without importing the code.
+ */
+export declare const SITE_HOST_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/site-host.v1.json';
+    readonly title: 'NormalizedSiteHost';
+    readonly description: 'A normalized sub-site host (the multi-site `site` dimension): lowercase, no protocol, no path, no port. null denotes a project-wide (unattributed) row.';
+    readonly type: readonly ['string', 'null'];
+    readonly pattern: '^[a-z0-9.-]+$';
+};

package/dist/sites.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// src/contracts/sites-normalize.ts
+function normalizeSiteHost(site) {
+  if (!site || typeof site !== "string") return null;
+  let s = site.trim().toLowerCase();
+  if (!s) return null;
+  s = s.replace(/^https?:\/\//, "");
+  const slash = s.indexOf("/");
+  if (slash >= 0) s = s.slice(0, slash);
+  const colon = s.indexOf(":");
+  if (colon >= 0) s = s.slice(0, colon);
+  s = s.replace(/\.+$/, "");
+  return s || null;
+}
+
+// src/contracts/sites.ts
+var SITE_HOST_CONTRACT_VERSION = 1;
+function stripWww(host) {
+  return host.startsWith("www.") ? host.slice(4) : host;
+}
+function sameSite(a, b) {
+  if (!a || !b) return false;
+  return stripWww(a) === stripWww(b);
+}
+function hostFromUrl(value) {
+  if (!value || !value.startsWith("http://") && !value.startsWith("https://")) return null;
+  try {
+    return normalizeSiteHost(new URL(value).host);
+  } catch {
+    return null;
+  }
+}
+function isNormalizedSiteHost(value) {
+  return typeof value === "string" && value.length > 0 && normalizeSiteHost(value) === value;
+}
+var SITE_HOST_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/site-host.v1.json",
+  title: "NormalizedSiteHost",
+  description: "A normalized sub-site host (the multi-site `site` dimension): lowercase, no protocol, no path, no port. null denotes a project-wide (unattributed) row.",
+  type: ["string", "null"],
+  pattern: "^[a-z0-9.-]+$"
+};
+
+exports.SITE_HOST_CONTRACT_VERSION = SITE_HOST_CONTRACT_VERSION;
+exports.SITE_HOST_JSON_SCHEMA = SITE_HOST_JSON_SCHEMA;
+exports.hostFromUrl = hostFromUrl;
+exports.isNormalizedSiteHost = isNormalizedSiteHost;
+exports.normalizeSiteHost = normalizeSiteHost;
+exports.sameSite = sameSite;
+exports.stripWww = stripWww;

package/dist/sites.mjs

@@ -0,0 +1,44 @@
+// src/contracts/sites-normalize.ts
+function normalizeSiteHost(site) {
+  if (!site || typeof site !== "string") return null;
+  let s = site.trim().toLowerCase();
+  if (!s) return null;
+  s = s.replace(/^https?:\/\//, "");
+  const slash = s.indexOf("/");
+  if (slash >= 0) s = s.slice(0, slash);
+  const colon = s.indexOf(":");
+  if (colon >= 0) s = s.slice(0, colon);
+  s = s.replace(/\.+$/, "");
+  return s || null;
+}
+
+// src/contracts/sites.ts
+var SITE_HOST_CONTRACT_VERSION = 1;
+function stripWww(host) {
+  return host.startsWith("www.") ? host.slice(4) : host;
+}
+function sameSite(a, b) {
+  if (!a || !b) return false;
+  return stripWww(a) === stripWww(b);
+}
+function hostFromUrl(value) {
+  if (!value || !value.startsWith("http://") && !value.startsWith("https://")) return null;
+  try {
+    return normalizeSiteHost(new URL(value).host);
+  } catch {
+    return null;
+  }
+}
+function isNormalizedSiteHost(value) {
+  return typeof value === "string" && value.length > 0 && normalizeSiteHost(value) === value;
+}
+var SITE_HOST_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/site-host.v1.json",
+  title: "NormalizedSiteHost",
+  description: "A normalized sub-site host (the multi-site `site` dimension): lowercase, no protocol, no path, no port. null denotes a project-wide (unattributed) row.",
+  type: ["string", "null"],
+  pattern: "^[a-z0-9.-]+$"
+};
+
+export { SITE_HOST_CONTRACT_VERSION, SITE_HOST_JSON_SCHEMA, hostFromUrl, isNormalizedSiteHost, normalizeSiteHost, sameSite, stripWww };

package/dist/slots.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @sonordev/contracts/slots — Managed Slots wire contract (v1)
+ *
+ * Single source of truth for the slot payload shape and content signing,
+ * shared by site-kit (verify side) and sonor-api (sign side). 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.
+ */
+/** Bump on breaking payload changes. */
+export declare const SLOTS_CONTRACT_VERSION = 1;
+/**
+ * v1 supports plain text only — rendered as React text (escaped), never
+ * dangerouslySetInnerHTML. 'markdown' / 'rich' are reserved for a future
+ * contract version behind a real sanitizer decision.
+ */
+export type SlotContentType = 'text';
+export declare const SLOT_CONTENT_TYPES: readonly SlotContentType[];
+/** Hard cap on managed content length; longer payloads are rejected → fallback. */
+export declare const SLOT_CONTENT_MAX_LENGTH = 10000;
+/** Slot ids: lowercase, page-scoped by convention, e.g. "home-hero-headline". */
+export declare const SLOT_ID_PATTERN: RegExp;
+export interface SlotContent {
+    slot_id: string;
+    type: SlotContentType;
+    /** The managed text. Rendered escaped — never as HTML. */
+    content: string;
+    /** Forward-compat: experiment/personalization variant that produced this content. */
+    variant_id?: string | null;
+    experiment_id?: string | null;
+    /** ISO timestamp of the last content change. */
+    updated_at?: string | null;
+    /** Hex HMAC-SHA256 over the canonical payload, keyed with the project API key. */
+    signature: string;
+}
+export interface SlotResolveRequestEntry {
+    id: string;
+    /**
+     * The developer's current static text for this slot (when statically
+     * extractable). Stored as `fallback_text` on registration so the dashboard
+     * editor shows the live copy instead of a bare slot id. Never rendered by
+     * the API anywhere — display + drafting context only.
+     */
+    fallback?: string;
+    /**
+     * The route this slot renders on (e.g. "/" or "/pricing"). A static literal,
+     * never derived from the request — it feeds the Copy Evidence Loop's
+     * slot↔page mapping so Signal can judge the slot against its page's metrics.
+     */
+    page?: string;
+}
+export interface SlotsResolveRequest {
+    contract_version: number;
+    slots: SlotResolveRequestEntry[];
+    /** Multi-site sub-dimension: normalized lowercase host (see CLAUDE.md "site" convention). */
+    site?: string;
+}
+export interface SlotsResolveResponse {
+    contract_version: number;
+    slots: Record<string, SlotContent | null>;
+}
+export declare function isValidSlotId(id: string): boolean;
+/**
+ * Canonical string both sides sign/verify. Exported separately from the HMAC
+ * helpers so an edge-runtime resolver can reproduce it with WebCrypto.
+ */
+export declare function slotSigningPayload(content: Pick<SlotContent, 'slot_id' | 'type' | 'content'>): string;
+/**
+ * Sign slot content with the project API key (sonor-api side).
+ * Returns the hex HMAC-SHA256 signature.
+ */
+export declare function signSlotContent(content: Pick<SlotContent, 'slot_id' | 'type' | 'content'>, apiKey: string): string;
+/**
+ * Verify a slot payload's shape + signature (site-kit side).
+ * Returns true only when the payload is well-formed, within limits, and the
+ * signature matches the project API key. Constant-time comparison.
+ */
+export declare function verifySlotContent(content: unknown, apiKey: string): content is SlotContent;

package/dist/slots.js

@@ -0,0 +1,44 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/contracts/slots.ts
+var SLOTS_CONTRACT_VERSION = 1;
+var SLOT_CONTENT_TYPES = ["text"];
+var SLOT_CONTENT_MAX_LENGTH = 1e4;
+var SLOT_ID_PATTERN = /^[a-z0-9][a-z0-9-_.:]{0,127}$/;
+function isValidSlotId(id) {
+  return SLOT_ID_PATTERN.test(id);
+}
+function slotSigningPayload(content) {
+  return `sonor-slot.v${SLOTS_CONTRACT_VERSION}
+${content.slot_id}
+${content.type}
+${content.content}`;
+}
+function signSlotContent(content, apiKey) {
+  return crypto.createHmac("sha256", apiKey).update(slotSigningPayload(content), "utf8").digest("hex");
+}
+function verifySlotContent(content, apiKey) {
+  if (!content || typeof content !== "object") return false;
+  const c = content;
+  if (typeof c.slot_id !== "string" || !isValidSlotId(c.slot_id) || typeof c.content !== "string" || c.content.length === 0 || c.content.length > SLOT_CONTENT_MAX_LENGTH || typeof c.signature !== "string" || !SLOT_CONTENT_TYPES.includes(c.type)) {
+    return false;
+  }
+  const expected = signSlotContent(
+    { slot_id: c.slot_id, type: c.type, content: c.content },
+    apiKey
+  );
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(c.signature, "utf8");
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+exports.SLOTS_CONTRACT_VERSION = SLOTS_CONTRACT_VERSION;
+exports.SLOT_CONTENT_MAX_LENGTH = SLOT_CONTENT_MAX_LENGTH;
+exports.SLOT_CONTENT_TYPES = SLOT_CONTENT_TYPES;
+exports.SLOT_ID_PATTERN = SLOT_ID_PATTERN;
+exports.isValidSlotId = isValidSlotId;
+exports.signSlotContent = signSlotContent;
+exports.slotSigningPayload = slotSigningPayload;
+exports.verifySlotContent = verifySlotContent;

package/dist/slots.mjs

@@ -0,0 +1,35 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
+// src/contracts/slots.ts
+var SLOTS_CONTRACT_VERSION = 1;
+var SLOT_CONTENT_TYPES = ["text"];
+var SLOT_CONTENT_MAX_LENGTH = 1e4;
+var SLOT_ID_PATTERN = /^[a-z0-9][a-z0-9-_.:]{0,127}$/;
+function isValidSlotId(id) {
+  return SLOT_ID_PATTERN.test(id);
+}
+function slotSigningPayload(content) {
+  return `sonor-slot.v${SLOTS_CONTRACT_VERSION}
+${content.slot_id}
+${content.type}
+${content.content}`;
+}
+function signSlotContent(content, apiKey) {
+  return createHmac("sha256", apiKey).update(slotSigningPayload(content), "utf8").digest("hex");
+}
+function verifySlotContent(content, apiKey) {
+  if (!content || typeof content !== "object") return false;
+  const c = content;
+  if (typeof c.slot_id !== "string" || !isValidSlotId(c.slot_id) || typeof c.content !== "string" || c.content.length === 0 || c.content.length > SLOT_CONTENT_MAX_LENGTH || typeof c.signature !== "string" || !SLOT_CONTENT_TYPES.includes(c.type)) {
+    return false;
+  }
+  const expected = signSlotContent(
+    { slot_id: c.slot_id, type: c.type, content: c.content },
+    apiKey
+  );
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(c.signature, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export { SLOTS_CONTRACT_VERSION, SLOT_CONTENT_MAX_LENGTH, SLOT_CONTENT_TYPES, SLOT_ID_PATTERN, isValidSlotId, signSlotContent, slotSigningPayload, verifySlotContent };

package/dist/website.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @sonordev/contracts/website — what a site's design is, and what a
+ * popup is made of. Pure: no DOM, no network, no React.
+ *
+ * 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
+ *    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`.
+ *
+ * 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
+ * image, a button); the site's measured design says HOW (colors, fonts,
+ * radius). Nothing in a block chooses a color or a font.
+ */
+/** Bumped when the token shape changes; sent with every report. */
+export declare const DESIGN_TOKENS_VERSION = 1;
+export interface SiteDesignTokens {
+    version: typeof DESIGN_TOKENS_VERSION;
+    colors: {
+        /** The page background. */
+        background: string;
+        /** A card or popup surface (the page background when the site has none). */
+        surface: string;
+        /** Body text. */
+        text: string;
+        /** Secondary text. */
+        muted: string;
+        /** The accent: buttons and links. */
+        primary: string;
+        /** Text on the accent, chosen for contrast when the site doesn't say. */
+        onPrimary: string;
+        /** Hairlines and card borders. */
+        border: string;
+    };
+    fonts: {
+        /** CSS font-family stacks, as the site declares them. */
+        body: string;
+        heading: string;
+    };
+    radius: {
+        /** Buttons and inputs. */
+        control: string;
+        /** Cards and popups. */
+        card: string;
+    };
+    /** How the site's buttons set text. */
+    button: {
+        textTransform: 'none' | 'uppercase';
+        fontWeight: string;
+    };
+    /** Light or dark, from the background's luminance. */
+    scheme: 'light' | 'dark';
+    /** Where the tokens came from: declared on SiteKitLayout, measured from the page, or both. */
+    source: 'declared' | 'measured' | 'mixed';
+}
+/** A CSS color (hex, rgb(), hsl()) as `#rrggbb`, or null for anything else or transparent. */
+export declare function toHexColor(value: unknown): string | null;
+/** `a` moved `t` (0-1) of the way toward `b`, both `#rrggbb`. */
+export declare function mixHex(a: string, b: string, t: number): string;
+/** '#ffffff' or '#111827', whichever reads better on `hex` (WCAG contrast). */
+export declare function readableOn(hex: string): '#ffffff' | '#111827';
+/**
+ * A design report (from the site, or anything claiming to be one) as
+ * SiteDesignTokens, or null when there isn't enough to draw with (no usable
+ * background, text or primary color). Missing pieces fall back to
+ * reasonable values derived from the ones present.
+ */
+export declare function normalizeDesignTokens(input: unknown): SiteDesignTokens | null;
+/** A stable hash of the tokens (FNV-1a over sorted JSON), to report only on change. */
+export declare function designTokensHash(tokens: SiteDesignTokens): string;
+/**
+ * The tokens as CSS custom properties. SINGLE SOURCE OF TRUTH for the names:
+ * the site sets them on :root (so popups render in its design) and the
+ * dashboard sets them on the preview frame (so the preview matches).
+ */
+export declare function designTokenCssVars(tokens: SiteDesignTokens): Record<string, string>;
+export type PopupBlock = {
+    type: 'heading';
+    text: string;
+} | {
+    type: 'text';
+    html: string;
+} | {
+    type: 'image';
+    url: string;
+    alt: string;
+} | {
+    type: 'button';
+    text: string;
+    url: string;
+    variant: 'primary' | 'secondary';
+} | {
+    type: 'divider';
+};
+export declare const POPUP_BLOCK_TYPES: readonly ['heading', 'text', 'image', 'button', 'divider'];
+export declare const POPUP_BLOCK_LIMITS: {
+    readonly blocks: 12;
+    readonly heading: 120;
+    /** Sanitized HTML length for one text block. */
+    readonly textHtml: 4000;
+    /** Visible characters across one text block. */
+    readonly textPlain: 1200;
+    readonly buttonText: 40;
+    readonly imageAlt: 200;
+    readonly buttons: 2;
+    readonly images: 3;
+};
+/**
+ * A link or image target a popup may use. Links: a path on the site (`/sale`,
+ * never `//host` or `/\host`), an anchor (`#offer`), http(s), mailto: or
+ * tel:. Images: https or a path on the site (an http image is blocked on an
+ * https page). Anything carrying a space or control character is refused,
+ * since browsers strip those before parsing ("java\tscript:" runs).
+ */
+export declare function isSafePopupUrl(value: unknown, kind?: 'link' | 'image'): boolean;
+/**
+ * A popup text block's HTML, reduced to the formatting a popup allows:
+ * paragraphs, line breaks, bold, italic, underline, strikethrough, lists and
+ * links (safe targets only; external links open in a new tab with
+ * rel="noopener noreferrer"). Every other tag is removed (its text kept,
+ * except script/style and friends, which go with their content); every
+ * attribute except a link's href is removed. Server-safe: no DOM.
+ */
+export declare function sanitizePopupHtml(html: unknown): string;
+/** The visible text of sanitized popup HTML (tags removed, common entities decoded). */
+export declare function popupHtmlText(html: string): string;
+/**
+ * Popup blocks from any input (the editor, an agent, a stored row), sanitized
+ * and checked against POPUP_BLOCK_LIMITS. `errors` says, in words a person
+ * can act on, what was wrong; a caller saving a popup refuses on any error,
+ * a renderer just draws `blocks`.
+ */
+export declare function normalizePopupBlocks(input: unknown): {
+    blocks: PopupBlock[];
+    errors: string[];
+};
+/** A popup's words in reading order: the accessible name source and the legacy plain-text fallback. */
+export declare function popupBlocksText(blocks: PopupBlock[]): {
+    heading: string;
+    body: string;
+};