@sonordev/site-kit 6.5.0 → 7.0.1

package/dist/contracts/portfolio.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @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`.
+ *
+ * Why it exists: generated case studies arrived with four "100/100 Lighthouse X"
+ * KPIs repeated across hero, results cards, and a Performance section. One
+ * differentiator repeated a dozen times stops differentiating — collapse the
+ * per-category Lighthouse tiles to at most one summary, business outcomes first.
+ *
+ * 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`.
+ */
+/** 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';
+export interface FrameReadyMessage {
+    type: typeof FRAME_READY_MESSAGE;
+    v: 1;
+}
+/** True for a {@link FrameReadyMessage}, for the embedder's message handler. */
+export declare function isFrameReadyMessage(data: unknown): data is FrameReadyMessage;
+/** Bump on breaking changes to the collapse policy. */
+export declare const PORTFOLIO_CONTRACT_VERSION: 1;
+/** Minimal KPI shape the policy reads — callers pass their own richer tiles. */
+export interface KpiLike {
+    label: string;
+    value: number;
+    description?: string;
+}
+/** True when a KPI tile is a per-category Lighthouse score. */
+export declare function isLighthouseKpi(kpi: Pick<KpiLike, 'label'>): boolean;
+/**
+ * Collapse per-category Lighthouse KPIs to at most one summary tile, business
+ * outcomes first. When every category is present at 100 the summary says so;
+ * otherwise the Performance category (the one buyers know) represents the set.
+ * Fewer than two Lighthouse tiles → returned unchanged.
+ */
+export declare function curateHeroKpis<T extends KpiLike>(kpis: T[]): T[];
+/**
+ * Agent-native contract: JSON Schema for the minimal KPI shape, so services and
+ * agents can validate tiles before applying the collapse policy.
+ */
+export declare const PORTFOLIO_KPI_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/portfolio-kpi.v1.json';
+    readonly title: 'KpiLike';
+    readonly description: 'The subset of a portfolio KPI tile the Lighthouse-collapse policy reads.';
+    readonly type: 'object';
+    readonly required: readonly ['label', 'value'];
+    readonly properties: {
+        readonly label: {
+            readonly type: 'string';
+        };
+        readonly value: {
+            readonly type: 'number';
+        };
+        readonly description: {
+            readonly type: 'string';
+        };
+        readonly source: {
+            readonly enum: readonly ['measured', 'reported', 'estimated'];
+        };
+        readonly reportedBy: {
+            readonly type: 'object';
+            readonly required: readonly ['name', 'organization', 'date'];
+            readonly properties: {
+                readonly name: {
+                    readonly type: 'string';
+                    readonly minLength: 1;
+                };
+                readonly role: {
+                    readonly type: 'string';
+                };
+                readonly organization: {
+                    readonly type: 'string';
+                    readonly minLength: 1;
+                };
+                readonly date: {
+                    readonly type: 'string';
+                    readonly pattern: '^\\d{4}-\\d{2}-\\d{2}$';
+                };
+            };
+        };
+    };
+    readonly if: {
+        readonly properties: {
+            readonly source: {
+                readonly const: 'reported';
+            };
+        };
+        readonly required: readonly ['source'];
+    };
+    readonly then: {
+        readonly required: readonly ['reportedBy'];
+    };
+    readonly additionalProperties: true;
+};
+/** Every source a portfolio number can have. */
+export declare const METRIC_SOURCES: readonly ['measured', 'reported', 'estimated'];
+export type MetricSource = (typeof METRIC_SOURCES)[number];
+/** Who stands behind a client-reported number. */
+export interface MetricAttribution {
+    /** The person, e.g. "Scott Mann". */
+    name: string;
+    /** Their title, e.g. "Director of Business Development". */
+    role?: string;
+    /** Where they work: almost always the client, e.g. "True Power Systems". */
+    organization: string;
+    /** The day they reported it, YYYY-MM-DD. */
+    date: string;
+}
+/** The provenance fields a portfolio number (a KPI tile, a results card) carries. */
+export interface SourcedMetric {
+    source?: string | null;
+    reportedBy?: unknown;
+}
+export declare function isMetricSource(value: unknown): value is MetricSource;
+/**
+ * What's wrong with a number's provenance, or null when nothing is. A missing
+ * source is legacy data and passes (displays show it unlabelled, and it can't
+ * headline); an unknown source, or a reported number nobody is named behind,
+ * does not.
+ */
+export declare function metricSourceProblem(metric: SourcedMetric): string | null;
+/**
+ * May this number lead: a hero tile, a gallery card, a carousel, a social
+ * post? Measured, or reported with someone named behind it. Never an
+ * estimate, and never an unlabelled legacy number.
+ */
+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,
+ * 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". */
+export declare function shortAttribution(by: Pick<MetricAttribution, 'organization'>): string;
+/**
+ * Carry a person's reported numbers through a regeneration. The generator can
+ * only write measured or estimated numbers (it can't see a client's books, and
+ * any 'reported' tag it writes is dropped here), so without this a rewrite of
+ * the hero or the results would silently erase what a client told us.
+ * Reported entries from `previous` lead, in their order; `next` fills in
+ * behind them, minus anything sharing a key with a reported entry.
+ */
+export declare function carryReportedMetrics<T extends SourcedMetric>(previous: readonly T[] | null | undefined, next: readonly T[] | null | undefined, keyOf: (metric: T) => string): T[];

package/dist/contracts/seo-meta.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @sonordev/contracts/seo-meta — generated title/description quality contract (v1)
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * Node built-ins.
+ */
+/** Bump on breaking changes to what counts as a problem. */
+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". */
+    brand?: string | null;
+    /** Other correct spellings of the brand. */
+    brandAliases?: Array<string | null | undefined>;
+    /** Hosts the site answers on, in any spelling (URL, www, port). */
+    hosts?: Array<string | null | undefined>;
+}
+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). */
+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;
+/** Everything after the last " | ", or null when the title has no suffix. */
+export declare function titleSuffix(title: string): string | null;
+/** Everything before the last " | ". */
+export declare function stripTitleSuffix(title: string): string;
+/**
+ * Why a title's brand suffix (the part after the last " | ") can't ship, or
+ * null when it can. Exposed so a generator can replace a bad suffix with the
+ * real brand instead of discarding the whole title.
+ */
+export declare function suffixProblem(suffix: string, id: MetaIdentity): SuffixProblem | null;
+/** Why a managed title can't ship, or null when it can. */
+export declare function titleProblem(title: string | null | undefined, id: MetaIdentity, opts?: {
+    path?: string | null;
+}): TitleProblem | null;
+/** Why a managed meta description can't ship, or null when it can. */
+export declare function descriptionProblem(description: string | null | undefined, id: MetaIdentity): DescriptionProblem | null;

package/dist/contracts/seo-pages.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @sonordev/contracts/seo-pages — seo_pages row resolution contract (v1)
+ *
+ * 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.
+ *
+ * seo_pages identity became (project_id, site, url) in sonor-api migration
+ * 20260702150000_seo_pages_per_site_identity.sql: 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
+ * read one deterministically via `pickSeoPageRow` instead.
+ *
+ * Pure data logic over row shapes (no I/O, no Node built-ins).
+ */
+/** Bump on breaking changes to the row-pick preference order. */
+export declare const SEO_PAGES_CONTRACT_VERSION: 1;
+/**
+ * Single source of truth for "this seo_pages row is still live" — apply as
+ * `.or(LIVE_SEO_PAGE_FILTER)` (PostgREST, in either API) on any read that
+ * represents the site's CURRENT content to the outside world.
+ *
+ * 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.
+ *
+ * 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
+ * index. A bare `.eq('status','active')` would drop it, and `.neq(...,'removed')`
+ * would too, because PostgREST evaluates NULL comparisons as NULL.
+ */
+export declare const LIVE_SEO_PAGE_FILTER = "status.is.null,status.eq.active";
+/** Minimal row shape `pickSeoPageRow` reads — callers pass their own richer rows. */
+export interface SeoPageRowLike {
+    site?: string | null;
+    updated_at?: string | null;
+}
+/**
+ * pickSeoPageRow — choose ONE row among per-site seo_pages rows sharing a
+ * path/url. Preference order:
+ *  1. exact `site` match (www-insensitive) when the caller knows the host
+ *  2. unattributed legacy row (site IS NULL)
+ *  3. the project's primary-domain row
+ *  4. most recently updated
+ */
+export declare function pickSeoPageRow<T extends SeoPageRowLike>(rows: T[], opts?: {
+    site?: string | null;
+    primaryHost?: string | null;
+}): T | null;
+/**
+ * matchSitemapEntryRow — choose the existing row a given host's write or read
+ * reconciles into. Lives here beside `pickSeoPageRow` because it is the same
+ * decision from the other direction: `pickSeoPageRow` answers "which row do I
+ * show when I don't have to care about the host", this answers "which row
+ * BELONGS to this host".
+ *
+ *  - site-tagged: the same host's row; else CLAIM an unattributed (NULL-site)
+ *    legacy row — a write stamps it with this host. Never matches another
+ *    host's row (this was the site flip-flop bug: shared paths collapsed into
+ *    one row whose site tag swung to the last syncer). `null` means the path
+ *    is not this host's, which is a real answer, not a miss.
+ *  - site-less: deterministic pick via pickSeoPageRow (NULL-site → primary
+ *    domain → most recent).
+ *
+ * The single matcher for every by-path caller — sitemap registration, GSC
+ * metrics sync, runtime page registration, and the llms.txt page index
+ * (`scopeSeoPagesToSite`). Do not fork this rule.
+ */
+export declare function matchSitemapEntryRow<T extends SeoPageRowLike>(candidates: T[], site: string | null, primaryHost: string | null): T | null;
+/**
+ * scopeSeoPagesToSite — reduce a project's seo_pages rows to the ONE page set
+ * 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.
+ *
+ * Rules, per path, via `matchSitemapEntryRow`:
+ *  - this host's row wins outright
+ *  - an unattributed (NULL-site) row stands in when the host has none — legacy
+ *    rows from site-less syncs are genuinely ambiguous, and dropping them would
+ *    silently delete real pages from the one file AI crawlers read
+ *  - another host's row is never substituted; that path is simply not ours
+ *
+ * A site-less call is the legacy project-wide read: dedupe only, no filtering.
+ */
+export declare function scopeSeoPagesToSite<T extends SeoPageRowLike & {
+    path: string;
+}>(rows: T[], site: string | null | undefined, primaryHost: string | null | undefined): T[];
+/**
+ * Agent-native contract: JSON Schema for the minimal row shape, so services and
+ * agents can validate candidate rows before handing them to `pickSeoPageRow`.
+ */
+export declare const SEO_PAGE_ROW_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/seo-page-row.v1.json';
+    readonly title: 'SeoPageRowLike';
+    readonly description: 'The subset of an seo_pages row that determines per-site resolution.';
+    readonly type: 'object';
+    readonly properties: {
+        readonly site: {
+            readonly description: 'Normalized sub-site host, or null for a project-wide row.';
+            readonly type: readonly ['string', 'null'];
+        };
+        readonly updated_at: {
+            readonly description: 'ISO 8601 timestamp; ties in resolution break toward the most recent.';
+            readonly type: readonly ['string', 'null'];
+        };
+    };
+    readonly additionalProperties: true;
+};

package/dist/contracts/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/contracts/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/contracts/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/contracts/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;
+};

package/dist/cta-bar/CtaBar.d.ts

@@ -82,4 +82,3 @@ export type CtaBarActionProps<C extends React.ElementType | undefined = undefine
 } & (C extends React.ElementType ? Omit<React.ComponentPropsWithoutRef<C>, keyof CtaBarActionOwnProps | 'as'> : CtaBarActionDefaultAttributes);
 export declare function CtaBarAction<C extends React.ElementType | undefined = undefined>(props: CtaBarActionProps<C>): React.JSX.Element;
 export {};
-//# sourceMappingURL=CtaBar.d.ts.map

package/dist/cta-bar/CtaBarBehavior.d.ts

@@ -43,4 +43,3 @@ export declare function nextCompactState(state: {
  */
 export declare function isTextEntry(el: Pick<Element, 'tagName'> | null): boolean;
 export declare function CtaBarBehavior({ showAfter, hideOver, hideWhileTyping, compactOnScroll, track }: CtaBarBehaviorProps): import("react").JSX.Element;
-//# sourceMappingURL=CtaBarBehavior.d.ts.map