@sonordev/site-kit 7.1.1 → 7.2.0

package/dist/commerce/index.js

@@ -1,15 +1,15 @@
 'use client';
 import '../chunk-P5GB6NEO.js';
-import { useAnalyticsOptional } from '../chunk-7FWA3I6A.js';
+import { useAnalyticsOptional } from '../chunk-JWTQS5F5.js';
 import '../chunk-LCDVPAMR.js';
 import '../chunk-24QZEO3Q.js';
 import '../chunk-L2V5PUFN.js';
 import '../chunk-GJWI74ZZ.js';
 import '../chunk-43OCZ3JA.js';
 import '../chunk-EKBEOXTH.js';
-import { sonorFetch } from '../chunk-PXZ7LAOY.js';
-import '../chunk-OUNRFXDC.js';
-import '../chunk-6OL23QYD.js';
+import { sonorFetch } from '../chunk-D6ZC7XKZ.js';
+import '../chunk-K4ZHAURD.js';
+import '../chunk-F24FNCTK.js';
 import '../chunk-PKBMQBKP.js';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import React5, { useState, useEffect, useMemo, useRef, useCallback } from 'react';

package/dist/commerce/server.d.ts

@@ -4,7 +4,7 @@
  * Helpers for server-side rendering and dynamic routes.
  * Use in Next.js getStaticPaths, getStaticProps, or App Router.
  *
- * All data fetching goes through the Portal API.
+ * All data fetching goes through the Sonor API.
  */
 import type { CommerceOffering, OfferingType } from './types';
 interface ServerConfig {
@@ -102,8 +102,7 @@ export declare function getOfferingsResult(config: ServerConfig, options?: {
  * Uses POST /api/public/commerce/events — the same endpoint the client fetcher
  * uses — because the GET offerings list does NOT embed commerce_schedules,
  * which made this helper return events with empty `schedules[]` and forced
- * sites to hand-roll their own fetcher for any calendar UI (the Ludlow PTO
- * lesson). Falls back to the legacy offerings query if the events endpoint
+ * sites to hand-roll their own fetcher for any calendar UI. Falls back to the legacy offerings query if the events endpoint
  * is unavailable (older self-hosted API).
  */
 export declare function getUpcomingEvents(config: ServerConfig, options?: {
@@ -154,7 +153,7 @@ export declare function generateOfferingMetadata(offering: CommerceOffering | nu
 /**
  * Create a server config for API calls
  *
- * @param apiUrl - Portal API URL (e.g., 'https://api.sonor.io')
+ * @param apiUrl - Sonor API URL (e.g., 'https://api.sonor.io')
  * @param apiKey - Project API key
  * @param projectId - Project ID
  */

package/dist/contracts/color.d.ts

@@ -4,7 +4,7 @@
  * Single source of truth for turning a CSS colour string into something the
  * kit can reason about. Used at build time by the brand-profile extractor
  * (`src/brand/extract-brand-profile.ts`, theme detection) and in the browser
- * by Echo (`src/engage/brand-color.ts`, brand text contrast). Pure, no
+ * by Echo (`src/chat/brand-color.ts`, brand text contrast). Pure, no
  * imports, safe in both.
  */
 export type Rgb = {

package/dist/contracts/entries.d.ts

@@ -4,5 +4,5 @@
  * tsup config, its package.json check and the boundary test, so a new
  * contract is added in one place.
  */
-export declare const CONTRACT_ENTRIES: readonly ['forms', 'llms', 'slots', 'slot-content', 'site-cache', 'site-edit', 'website', 'color', 'fleet', 'sites', 'seo-pages', 'seo-meta', 'portfolio'];
+export declare const CONTRACT_ENTRIES: readonly ['forms', 'llms', 'slots', 'slot-content', 'site-cache', 'site-edit', 'website', 'color', 'fleet', 'sites', 'seo-pages', 'seo-meta', 'portfolio', 'voice', 'proposal-sitemap', 'error-page', 'schema-placeholders'];
 export type ContractEntry = (typeof CONTRACT_ENTRIES)[number];

package/dist/contracts/error-page.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @sonordev/contracts/error-page: telling an error page from a page (v1)
+ *
+ * Three questions every writer of page content and page copy has to answer the
+ * same way, so they live here once:
+ *
+ *   1. Is this stored text a rendered ERROR PAGE rather than the page's own
+ *      content? (`looksLikeErrorPage`, `usablePageText`)
+ *   2. Does this generated COPY say the page itself is missing or unavailable?
+ *      (`findErrorPageClaim`, `describesErrorPage`)
+ *   3. Does any string in a page's managed copy (a title, a keyword list, a
+ *      JSON-LD block) say so? (`findPageCopyClaim`: question 2 over every
+ *      string of a record, naming the field that holds it)
+ *
+ * Why it exists: a page's stored text is the text a visitor's browser (or a
+ * build's crawler) rendered. Visit a URL while it's briefly broken and the
+ * error page's words are stored as that page's content. Everything generated
+ * from that content then describes a working page as broken, and the result
+ * is published as the page's title, meta description, social tags, JSON-LD
+ * and AI-crawler notes. The outage ends in a deploy; the poisoned copy
+ * doesn't, because nothing downstream asks whether its input was ever the
+ * page.
+ *
+ * How the text check works
+ *
+ *   - It reads the START of the text (300 characters), lowercased, with
+ *     whitespace collapsed, HTML entities decoded and curly quotes made
+ *     straight. Error copy leads; articles bury it.
+ *   - The signatures are generic on purpose. Every site words its 404
+ *     differently and frameworks ship their own ("This page could not be
+ *     found.", "Application error: a client-side exception has occurred"), so
+ *     the shape is what's matched, not any one site's copy. They're grouped by
+ *     family below: not found, server and client errors, unavailable and
+ *     maintenance, walls.
+ *   - Stored text is often the page's elements run together with no separator
+ *     ("404This page could not be found."), so no signature depends on a word
+ *     boundary around the text it's matching.
+ *   - A signature that follows a word that DESCRIBES errors rather than
+ *     showing one ("if something went wrong", "how to fix a 404 error", a
+ *     quote mark) doesn't count: a help page that names an error isn't one.
+ *     Navigation is Title Case and prose isn't, so a describing word counts
+ *     only as it's written in lower case, with only its first letter
+ *     capitalized ("How to fix..."), or opening the text or a sentence;
+ *     "Home Blog How To Something went wrong" is still an error page, and the
+ *     words a menu uses too ("About", "Monitoring", "Alerts for") describe an
+ *     error only in lower case. A describing word inside the matched phrase
+ *     counts too, and after a described match the search resumes one character
+ *     on, so a real error later in the same stretch is still found.
+ *   - A not-found phrase that sits in a question ("Page not found? Use our site
+ *     map", "Product not found in your size? Ask us") is a help line, and so is
+ *     most copy that merely uses the words ("Rare parts can't be found
+ *     elsewhere": the subject has to be a page, URL, link, file, site or app).
+ *   - Up to ERROR_PAGE_MAX_WORDS words every check applies, but the loosest
+ *     ones apply only to the shortest texts: a 404 glued to its copy and
+ *     "refresh the page and try again" up to 60 words, a dynamic route's own
+ *     "<name> not found" state up to 40. From there up to 400 words only the
+ *     prefix-aware check applies: a text written as "<meta description> —
+ *     <every string on the page>" carries its header and footer strings along,
+ *     which pushes a rendered error state past the short-text ceiling, so the
+ *     check looks at how the text opens after the description and a skip link,
+ *     and an opener followed by "explained" or "how to" is an article. Beyond
+ *     400 words the text is prose.
+ *
+ * `wordCount` semantics: pass the word count of `text` itself. Pass the whole
+ * document's count only when `text` is a truncated excerpt of it. A supplied
+ * count can only RAISE the count the check uses (an excerpt of a long document
+ * is prose however short it is), never lower it: text that is longer than the
+ * count you gave is counted by what it holds. A browser's page-wide count
+ * (navigation and footer included) is therefore the wrong number for a short
+ * error state it scraped: pass the count of the text you pass.
+ *
+ * How the copy check works
+ *
+ *   `findErrorPageClaim` looks for the copy saying THE PAGE is missing or
+ *   unavailable ("Page Not Found | Acme", "This URL currently returns a 404",
+ *   "This listing has been removed", "The page failed to load"). The subject
+ *   has to be the page, its URL, link or listing, so copy about something
+ *   unavailable on a working page ("sunset cruises are not available at this
+ *   time") is left alone, and so is a qualified one ("unavailable in winter").
+ *   Whitespace is collapsed and each string is read up to 5,000 characters, so
+ *   hostile whitespace costs nothing. The page's own text exempts a phrase the
+ *   page really says; a page that is itself an error page exempts nothing.
+ *
+ *   `findPageCopyClaim(fields, pageText?)` is the same check over a record:
+ *   each value of `fields` is checked if it's a string, and walked for every
+ *   string it holds if it's an array or an object (8 levels deep, 2,000
+ *   leaves at most; numbers, booleans and null are ignored). It returns the
+ *   first claim as `{ field, phrase }`, `field` being the TOP-LEVEL key (the
+ *   column or property that holds the copy), or null. Use it for a page row's
+ *   managed title, description, keywords and JSON-LD in one call.
+ *
+ * Known limits (a text-only check can't close these)
+ *
+ *   - Any error phrase in the first 300 characters of a text of 120 words or
+ *     fewer reads as an error page, wherever in those 300 characters it sits, unless
+ *     something describes it (see above): a short page ABOUT errors ("Page not
+ *     found: how to design a helpful 404 page. Five examples.", or a web
+ *     agency's line about its "custom 404 error page") can be misread. Texts of
+ *     121 to 400 words are only read for how they open, and longer ones are
+ *     prose. The loosest wordings (a 404 glued to its copy, "refresh the page
+ *     and try again", "<name> not found") apply only up to 60, 60 and 40 words.
+ *   - A business whose name is an error phrase ("404 Brewing Co.", "Page Not
+ *     Found Records") reads as an error page when its name leads the text.
+ *   - Chrome in front hides the error state from the wordings anchored to the
+ *     start of the text ("Not Found", "Be right back.", "Error: ...", "Oops!
+ *     This page...", a permission wall, a dynamic route's "<name> not found").
+ *     The wordings that hold anywhere in the first 300 characters (a status with
+ *     its reason, "could not be found", "something went wrong") are what's
+ *     left. Prefer the page's main content.
+ *   - The text alone never proves a page failed. Where a call site observed
+ *     the HTTP status (a browser reports it), require a status of 400 or more
+ *     as well, and treat this check as the fallback for the sites and the
+ *     paths that report none.
+ *   - It reads English. A 404 in another language isn't matched.
+ *   - Walls and pages served by the host in front of the site (a CDN block, a
+ *     bot challenge, a parked domain, a default server page, a browser
+ *     interstitial) never reach the writers this guards, so they aren't
+ *     matched here.
+ *   - Copy that claims the page is missing in words outside the closed list
+ *     below isn't caught; the real protection is that error text never reaches
+ *     the generator (`usablePageText`).
+ *
+ * Pure string logic: no I/O, no Node built-ins, no lookbehind (this ships to
+ * browsers, and Safari before 16.4 throws on a lookbehind at parse time).
+ */
+/** Bump on breaking changes to what counts as an error page or an error claim. */
+export declare const ERROR_PAGE_CONTRACT_VERSION: 1;
+/**
+ * Above this many words, text is real prose even if it mentions a 404: only
+ * the prefix-aware check (up to 400 words, see the header) still looks at it.
+ *
+ * The gate is what makes the check safe: an article about broken links ("How
+ * to fix 404 errors on your site") legitimately holds every phrase below and
+ * must not be discarded. A rendered error page is short, and this ceiling
+ * still separates the two by an order of magnitude.
+ */
+export declare const ERROR_PAGE_MAX_WORDS = 120;
+/**
+ * True when this text is a rendered error page rather than page content.
+ *
+ * @param text      the scraped or extracted body text
+ * @param wordCount the word count of `text` itself, or the whole document's
+ *                  when `text` is a truncated excerpt of it. It can only raise
+ *                  the count the check uses, never lower it; derived from
+ *                  `text` when absent.
+ */
+export declare function looksLikeErrorPage(text?: string | null, wordCount?: number | null): boolean;
+/**
+ * The page's stored text, or null when it's an error page. What a model may
+ * be shown as "the page's content".
+ */
+export declare function usablePageText(text?: string | null, wordCount?: number | null): string | null;
+/**
+ * The phrase in `copy` that says the page itself is missing or unavailable, or
+ * null when the copy is fine.
+ *
+ * @param pageText the page's own text. A phrase the page really says (an
+ *                 article about fixing "page not found" errors) is allowed;
+ *                 only copy that claims what the page doesn't is a finding.
+ *                 A pageText that is itself an error page allows nothing: its
+ *                 words are the poison, so the copy that repeats them would
+ *                 otherwise vouch for itself.
+ */
+export declare function findErrorPageClaim(copy?: string | null, pageText?: string | null): string | null;
+/** True when `copy` says the page itself is missing or unavailable (see `findErrorPageClaim`). */
+export declare function describesErrorPage(copy?: string | null, pageText?: string | null): boolean;
+/**
+ * The first string anywhere in a record of managed copy that says the page
+ * itself is missing or unavailable, or null. `findErrorPageClaim` over every
+ * string of `fields`, and the record's own field name with the phrase.
+ *
+ * Each value is checked if it's a string, and walked for the strings it holds
+ * if it's an array or an object (a JSON-LD block, a keyword list), up to 8
+ * levels deep, 2,000 strings and 100,000 characters in all; numbers, booleans and
+ * null are ignored (and don't count toward those limits).
+ * `field` is the TOP-LEVEL key, the column or property that holds the copy.
+ * `pageText` exempts what the page really says, as in `findErrorPageClaim`; the
+ * page's own text is read once for the whole record.
+ */
+export declare function findPageCopyClaim(fields: object, pageText?: string | null): {
+    field: string;
+    phrase: string;
+} | null;

package/dist/contracts/fleet.d.ts

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

package/dist/contracts/forms.d.ts

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

package/dist/contracts/llms.d.ts

@@ -14,7 +14,7 @@ export declare const LLMS_PUBLIC_SUMMARY_MAX_LENGTH = 400;
 /** Max length for optional llms.txt blockquote disclaimer line. */
 export declare const LLMS_DISCLAIMER_MAX_LENGTH = 280;
 /**
- * Optional keys we allow inside managed_llm_schema JSON from Portal.
+ * Optional keys we allow inside managed_llm_schema JSON from Sonor.
  * Values outside this set should not be relied on by consumers; strip unknown keys when emitting JSON-LD.
  */
 export declare const MANAGED_LLM_SCHEMA_KNOWN_KEYS: Set<string>;
@@ -28,6 +28,7 @@ export interface LLMsPayloadMeta {
     /** Optional single-line, public-safe note in the llms.txt blockquote (e.g. scope / not legal advice). */
     llms_disclaimer?: string | null;
 }
+export declare function clipAtWordBoundary(text: string, max: number): string;
 /**
  * Public-safe summary for llms.txt `[title](url): notes` — never CRM-only or internal copy.
  */

package/dist/contracts/portfolio.d.ts

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

package/dist/contracts/proposal-sitemap.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @sonordev/contracts/proposal-sitemap — how a proposal's site plan is counted (v1)
+ *
+ * Single source of truth for the numbers a website proposal's site plan
+ * (the `SitemapPlan` block) states: how many pages the build has, when the
+ * "before → after" comparison may show, which custom labels the block may
+ * carry, and whether page counts written elsewhere in the proposal agree with
+ * the plan. The proposal generator stamps them, the Sonor API checks them and
+ * the dashboard renders them, so the headline, the plan and the price can't
+ * each state a different number.
+ *
+ * Why it exists: the numbers in a plan are what a buyer reads first, and a
+ * count written by a language model can't be trusted to add up. A rebuild
+ * that keeps every page must never read as a loss ("24 → 0 pages"), one
+ * address listed twice must not count twice, and the headline must not state
+ * a number the plan doesn't. Counts are computed here, never taken from prose.
+ */
+/** Bump on breaking changes to how a plan is counted. */
+export declare const PROPOSAL_SITEMAP_CONTRACT_VERSION: 1;
+/**
+ * A count the plan states: a non-negative whole number, as a number or a
+ * numeric string. Anything else is no count at all (undefined), never 0.
+ */
+export declare function sitemapCount(v: unknown): number | undefined;
+/**
+ * The address a plan row stands for, in one shape: lowercase, no scheme or
+ * host, no query or fragment, a leading slash and no trailing one ("/" for the
+ * home page). Undefined for a row without a slug; such a row always counts,
+ * since nothing proves it repeats another.
+ */
+export declare function sitemapPageKey(slug: unknown): string | undefined;
+export interface SitemapPlanCounts {
+    /** Core pages (Home, About, Contact and the like), each address once. */
+    core: number;
+    /**
+     * The plan's own pages: top-level pages plus the pages under them, minus
+     * any address already counted as a core page.
+     */
+    architecture: number;
+    /** Existing articles re-published with the build (the plan's `blog.count`). */
+    articles: number;
+    /** Everything the client gets: core + architecture + articles. */
+    full: number;
+    /**
+     * Pages that exist today and carry over (status rebuild, optimize or
+     * migrate, plus the re-published articles).
+     */
+    existing: number;
+    /** Pages the build adds (status new, or no status). */
+    added: number;
+}
+/**
+ * Count a site plan's pages, each address once. Core pages are counted
+ * first, then each top-level page and the pages under it; a row whose
+ * address was already counted is skipped. Rows without a slug always count.
+ */
+export declare function countSitemapPlan(props: unknown): SitemapPlanCounts;
+export interface SitemapTransformationCounts {
+    /** Today's count, as the plan states it. */
+    before: number;
+    /** The build's count. */
+    after: number;
+}
+/**
+ * The before → after comparison a plan may show, or null when it must not
+ * show. It shows only when the plan states today's count and the build is
+ * bigger. A missing after-count falls back to the plan's own pages (then its
+ * `totalPages`); an after-count of zero, or one no bigger than today's, hides
+ * the comparison. A rebuild that keeps the same pages isn't a before and after.
+ */
+export declare function sitemapTransformation(props: unknown): SitemapTransformationCounts | null;
+/**
+ * Words a plan uses for its own pages, for a business whose pages aren't
+ * services sold to industries (communities and towns, practice areas,
+ * locations). Each replaces one default: `architecture` the heading
+ * ("Service Architecture"), `pillar` a top-level page ("Service pillar"),
+ * `child` a page under it ("Industry page"). Singular, title case.
+ */
+export interface SitemapPlanLabels {
+    architecture?: string;
+    pillar?: string;
+    child?: string;
+}
+/** The longest a label may be. */
+export declare const SITEMAP_LABEL_MAX = 40;
+/**
+ * Keep only usable labels: strings of 1 to {@link SITEMAP_LABEL_MAX}
+ * characters on one line, whitespace collapsed, no angle brackets. Undefined
+ * when none survive, so a plan without labels reads the defaults.
+ */
+export declare function normalizeSitemapLabels(raw: unknown): SitemapPlanLabels | undefined;
+export type PageCountUnit = 'page' | 'url';
+export interface PageCountClaim {
+    /** The number stated. */
+    value: number;
+    /** Whether it counts pages or URLs. */
+    unit: PageCountUnit;
+    /** The words that make the claim, e.g. "27 existing URLs". */
+    text: string;
+    /** Where the claim starts in the text. */
+    index: number;
+}
+/**
+ * Every page or URL count stated in a piece of text. A number that's part of
+ * a name ("Troy 7 Apartments get pages of their own") isn't a count.
+ */
+export declare function findPageCountClaims(text: unknown): PageCountClaim[];
+export interface PageCountIssue {
+    /** The block the claim is in, e.g. "GlassHero". */
+    section: string;
+    /** Where in the block, e.g. "stats[0]" or "tiers[0].features[1]". */
+    field: string;
+    /** The number stated. */
+    claimed: number;
+    unit: PageCountUnit;
+    /** The words that make the claim. */
+    text: string;
+    /** The page count the plan adds up to. */
+    planned: number;
+}
+/**
+ * Page and URL counts a proposal states that match nothing its site plan or
+ * its measured evidence adds up to. A stated count passes when it equals any
+ * of: the plan's full, core, own, article, carried-over or added page count;
+ * the plan's stated before-count; or the measured URL and page counts the
+ * evidence blocks carry. Empty when the proposal has no site plan.
+ */
+export declare function proposalPageCountIssues(sections: unknown): PageCountIssue[];
+/** One plain sentence for a person reviewing the proposal before it's sent. */
+export declare function describePageCountIssue(issue: PageCountIssue): string;

package/dist/contracts/schema-placeholders.d.ts

@@ -0,0 +1,87 @@
+/**
+ * JSON-LD template placeholders: found once, dropped wherever sonor-api serves
+ * stored schema to a site, and never stored as implemented by register-schema.
+ *
+ * Stored JSON-LD (seo_schema_markup.schema_json, seo_pages.managed_schema) can
+ * carry a template's unfilled slots. Schema extracted from a site's source,
+ * where the base URL was a variable, comes back as https://example.com; an AI
+ * filling a template leaves "Example", "+1-000-000-0000", "[Resident Name]",
+ * "{plan.name}", or an object that is only a "note" saying what goes there.
+ * site-kit renders all of it on the live page, where search engines and AI
+ * crawlers take it as the business's identity. Observed 2026-10-01: a live
+ * site served an Organization named "Example", phone +1-000-000-0000, on its
+ * home page, and dozens more of its implemented rows carried example.com URLs
+ * and unfilled template slots.
+ *
+ * Conservative on purpose, because a false positive removes real schema from a
+ * live site:
+ *   - Domains: only the reserved example domains (example.com, example.net,
+ *     example.org, their subdomains, and the .example TLD), and only when the
+ *     whole value is a URL, host or email address. A real domain with
+ *     "example" in its path, or prose that mentions example.com, is fine.
+ *   - Names: whole-value matches only (trimmed, case-insensitive) on name-like
+ *     properties. "Example Plumbing Co" is a real name.
+ *   - Phones (telephone, faxNumber, tel: links): all zeros, 123-456-7890,
+ *     XXX-XXX-XXXX, and 555-0100 through 555-0199, the North American range
+ *     reserved for fiction. 555-0200 and 555-1212 are real numbers.
+ *   - Template slots: a value that is wholly a bracketed slot ("[YYYY-MM-DD]")
+ *     or a JSX expression ("{plan.name}"), a {{mustache}} slot, a
+ *     REPLACE_WITH_ marker, a title-case field name in brackets inside text
+ *     ("Call [Phone Number]"), or a JSX member expression inside a URL. A URI
+ *     template's {search_term_string} is how schema.org spells a SearchAction
+ *     and is never a finding.
+ *   - Annotations: an object that holds nothing but an AI note. A note key on
+ *     a real node is stripped (it isn't schema.org vocabulary) and the node
+ *     stays.
+ *
+ * The unit is the NODE: the innermost object with @type or @id (or a top-level
+ * or @graph member) whose own values hold the placeholder. A placeholder node
+ * is dropped whole, since its other values came from the same unfilled
+ * template. Its real siblings, and a real parent it hangs off, stay: an
+ * FAQPage keeps its questions when only its publisher was a placeholder. A
+ * node left with nothing but JSON-LD keywords once its placeholder children
+ * are gone (a BreadcrumbList whose every item was a placeholder) goes too, so
+ * the site falls back to what it generates itself.
+ *
+ * Single source of truth for "is this stored schema a placeholder", published
+ * as `@sonordev/contracts/schema-placeholders`: sonor-api's public schema reads
+ * and register-schema, and site-kit's ManagedSchema and LLMSchema (so a site
+ * drops a placeholder whichever Sonor source served it) all call it. Add new
+ * shapes here, with a test, never in a caller.
+ */
+export type SchemaPlaceholderReason = 'example_domain' | 'placeholder_phone' | 'placeholder_name' | 'template_token' | 'annotation' | 'emptied';
+export interface SchemaPlaceholderEvidence {
+    reason: SchemaPlaceholderReason;
+    /** The property that held the value. */
+    key: string;
+    /** The value, cut short for logs. */
+    value: string;
+}
+export interface SchemaPlaceholderNode {
+    /** Where the node sits: '$' for the root, then .key and [index] steps. */
+    path: string;
+    /** The node's @type ('A,B' when it has several), or null. */
+    type: string | null;
+    reasons: SchemaPlaceholderReason[];
+    evidence: SchemaPlaceholderEvidence[];
+}
+export interface SchemaPlaceholderScan<T> {
+    /** The value without its placeholder nodes: the same reference when nothing was found, null when nothing real is left. */
+    value: T | null;
+    /** Every node removed, outermost only (a dropped node's children go with it). */
+    dropped: SchemaPlaceholderNode[];
+    /** AI note keys stripped from nodes that were kept. */
+    notes: Array<{
+        path: string;
+        key: string;
+    }>;
+}
+/**
+ * The value with its placeholder nodes removed, and what was removed. Pure; the
+ * input is never mutated.
+ */
+export declare function withoutSchemaPlaceholders<T>(value: T): SchemaPlaceholderScan<T>;
+/** Which nodes of a JSON-LD value are placeholders, and why. */
+export declare function findSchemaPlaceholders(value: unknown): SchemaPlaceholderNode[];
+/** One line a person can act on: 'Organization at $: name "Example" is a placeholder name'. */
+export declare function describeSchemaPlaceholder(node: SchemaPlaceholderNode): string;