@sonordev/contracts 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.4.0
+
+A minor release: one new entry, `@sonordev/contracts/schema-placeholders`, and the llms.txt sanitizers stop cutting mid-word. Every other entry is unchanged.
+
+- **New entry `@sonordev/contracts/schema-placeholders`**: whether stored JSON-LD carries a template's unfilled slots, so the API that serves it and the site that renders it drop the same nodes.
+  - `withoutSchemaPlaceholders(value)` returns `{ value, dropped, notes }`: the JSON-LD without its placeholder nodes (the same reference when nothing was found, `null` when nothing real is left), every node it removed with the reason and the evidence, and the AI note keys it stripped from nodes it kept.
+  - `findSchemaPlaceholders(value)` returns just the nodes, and `describeSchemaPlaceholder(node)` turns one into a line a person can act on.
+  - It finds reserved example domains (`example.com`, `example.net`, `example.org`, `.example`) in URLs, hosts and emails, whole-value template names ("Example", "Your Business Name"), placeholder phones, bracketed and JSX slots (`[Resident Name]`, `{plan.name}`, `{{business_name}}`), `REPLACE_WITH_` markers, and objects that are only a note. A URI template's `{search_term_string}`, a real name that contains "Example" and a 555 number outside the fiction range are left alone.
+- **`llms`**: `clipAtWordBoundary(text, max)` cuts prose to a length without splitting a word. It ends at a sentence when one closes in the last 40% of the window, otherwise at the last whole word with an ellipsis, and never returns more than `max` characters. `sanitizeLlmsPublicSummary` and `sanitizeLlmsDisclaimerLine` now cut with it, so a long summary ends at a sentence or a whole word instead of mid-word. The limits are unchanged (400 and 280).
+
 ## 2.3.0
 
 A minor release: one new entry, `@sonordev/contracts/error-page`. Every other entry is unchanged.

package/README.md

@@ -14,7 +14,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/sites` | The canonical shape of a site host (the multi-site `site` dimension) | every ingest and read that filters by site |
 | `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | the Sonor API, Signal, site-kit's sitemap sync |
 | `@sonordev/contracts/seo-meta` | Whether a title or description is fit to ship | site-kit, Signal's SEO gate |
-| `@sonordev/contracts/llms` | llms.txt sanitizers and contract version | site-kit, the Sonor API, Signal's schema validation |
+| `@sonordev/contracts/llms` | llms.txt sanitizers, the word-safe cut they use (`clipAtWordBoundary`), and the contract version | site-kit, the Sonor API, Signal's schema validation |
 | `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, the Sonor API's form intake |
 | `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, the Sonor API |
 | `@sonordev/contracts/slots` | Slot payload signing, contract v2 (HMAC; Node only). Signs and verifies v1 for older site-kit releases | the Sonor API, site-kit on the server |
@@ -25,6 +25,41 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/proposal-sitemap` | How a proposal's site plan counts its pages, when its before-and-after comparison may show, and whether the page counts stated elsewhere in the proposal add up | the Sonor API, Signal's proposal writer, the dashboard's proposal pages |
 | `@sonordev/contracts/voice` | The house voice's contraction rule. `findUncontracted` and `contractText` find and apply full forms that should be contractions; `findContracted` finds the contractions a question-form heading should expand | anything that checks or rewrites copy: Sonor's APIs and dashboard |
 | `@sonordev/contracts/error-page` | Whether stored text is a rendered error page rather than a page's content, and whether generated copy says the page itself is missing | anything that stores page text or writes page copy from it: the Sonor API's page-view and sitemap writers, Signal's metadata generators |
+| `@sonordev/contracts/schema-placeholders` | Whether stored JSON-LD carries a template's unfilled slots (`example.com` URLs, an `Organization` named "Example", a placeholder phone, `[Resident Name]`, `{plan.name}`), and the value without them | site-kit's schema output, the Sonor API's schema reads and writes |
+
+## Schema placeholders
+
+`schema-placeholders` finds the parts of a JSON-LD value that a template left
+unfilled, so a site never publishes them as the business's identity. Schema
+extracted from a site's source, where the base URL was a variable, comes back
+as `https://example.com`; a template filled in by hand or by an AI can leave
+"Example", `+1-000-000-0000`, `[Resident Name]`, `{plan.name}`, or an object
+that's only a note about what goes there.
+
+```ts
+import { withoutSchemaPlaceholders, describeSchemaPlaceholder } from '@sonordev/contracts/schema-placeholders'
+
+const { value, dropped } = withoutSchemaPlaceholders(storedJsonLd)
+// value: the JSON-LD without its placeholder nodes (the same reference when
+// nothing was found, null when nothing real is left)
+dropped.map(describeSchemaPlaceholder)
+// ['Organization at $: name "Example" is a placeholder name']
+```
+
+- **The unit is the node.** The innermost object with an `@type` or `@id` (or
+  a top-level or `@graph` member) whose own values hold the placeholder is
+  dropped whole. Its real siblings, and a real parent it hangs off, stay. A
+  node left with nothing but JSON-LD keywords once its placeholder children are
+  gone goes too.
+- **Conservative on purpose.** A false positive removes real schema from a live
+  site, so names match whole values only ("Example Plumbing Co" is a real
+  name), domains are only the reserved example domains, phones are only
+  all-zero, sequential, `XXX` and the 555-0100 to 555-0199 fiction range, and a
+  URI template's `{search_term_string}` is how schema.org spells a
+  `SearchAction`, never a finding.
+- **Notes.** An AI's `note` key on a real node isn't schema.org vocabulary: it's
+  stripped and the node stays. An object that's only a note is dropped.
+- **Pure.** The input is never mutated.
 
 ## The voice contract
 

package/dist/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/llms.d.ts

@@ -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/llms.js

@@ -18,14 +18,64 @@ var MANAGED_LLM_SCHEMA_KNOWN_KEYS = /* @__PURE__ */ new Set([
   "speakable",
   "additionalType"
 ]);
+var SENTENCE_SHARE = 0.4;
+var ELLIPSIS = "\u2026";
+var CLOSERS = /* @__PURE__ */ new Set(['"', "'", ")", "]", "\u201D", "\u2019", "\xBB"]);
+var ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "mr",
+  "mrs",
+  "ms",
+  "dr",
+  "prof",
+  "st",
+  "mt",
+  "ft",
+  "jr",
+  "sr",
+  "inc",
+  "ltd",
+  "co",
+  "corp",
+  "vs",
+  "no"
+]);
+var TRAILING_SEPARATORS = /[\s.,;:\-\u2013\u2014/&([{]+$/;
+function clipAtWordBoundary(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (flat.length <= max) return flat;
+  if (max < 2) return flat.slice(0, Math.max(0, max));
+  const floor = Math.floor(max * (1 - SENTENCE_SHARE));
+  for (let end = max; end > floor; end--) {
+    if (endsSentence(flat, end)) return flat.slice(0, end);
+  }
+  const room = max - 1;
+  const space = flat.lastIndexOf(" ", room);
+  if (space <= 0) return `${flat.slice(0, room)}${ELLIPSIS}`;
+  if (endsSentence(flat, space)) return flat.slice(0, space);
+  const head = flat.slice(0, space).replace(TRAILING_SEPARATORS, "");
+  return `${head || flat.slice(0, room)}${ELLIPSIS}`;
+}
+function endsSentence(flat, end) {
+  if (flat[end] !== " ") return false;
+  let i = end - 1;
+  while (i > 0 && CLOSERS.has(flat[i])) i--;
+  const terminator = flat[i];
+  if (terminator === "!" || terminator === "?") return true;
+  return terminator === "." && !isAbbreviation(flat, i);
+}
+function isAbbreviation(flat, dot) {
+  let start = dot;
+  while (start > 0 && flat[start - 1] !== " ") start--;
+  const token = flat.slice(start, dot).replace(/^[("'[\u201c\u2018]+/, "").toLowerCase();
+  if (token.includes(".") || /^[a-z]$/.test(token)) return true;
+  return ABBREVIATIONS.has(token);
+}
 function sanitizeLlmsPublicSummary(raw) {
   if (raw === null || raw === void 0) return null;
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_PUBLIC_SUMMARY_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_PUBLIC_SUMMARY_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_PUBLIC_SUMMARY_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 8) return null;
@@ -36,9 +86,7 @@ function sanitizeLlmsDisclaimerLine(raw) {
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_DISCLAIMER_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_DISCLAIMER_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_DISCLAIMER_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 3) return null;
@@ -100,6 +148,7 @@ exports.LLMS_DISCLAIMER_MAX_LENGTH = LLMS_DISCLAIMER_MAX_LENGTH;
 exports.LLMS_PUBLIC_SUMMARY_MAX_LENGTH = LLMS_PUBLIC_SUMMARY_MAX_LENGTH;
 exports.LLM_GEO_CONTRACT_VERSION = LLM_GEO_CONTRACT_VERSION;
 exports.MANAGED_LLM_SCHEMA_KNOWN_KEYS = MANAGED_LLM_SCHEMA_KNOWN_KEYS;
+exports.clipAtWordBoundary = clipAtWordBoundary;
 exports.isEmittableReviewNode = isEmittableReviewNode;
 exports.pickManagedLlmSchemaForJsonLd = pickManagedLlmSchemaForJsonLd;
 exports.sanitizeLlmsDisclaimerLine = sanitizeLlmsDisclaimerLine;

package/dist/llms.mjs

@@ -16,14 +16,64 @@ var MANAGED_LLM_SCHEMA_KNOWN_KEYS = /* @__PURE__ */ new Set([
   "speakable",
   "additionalType"
 ]);
+var SENTENCE_SHARE = 0.4;
+var ELLIPSIS = "\u2026";
+var CLOSERS = /* @__PURE__ */ new Set(['"', "'", ")", "]", "\u201D", "\u2019", "\xBB"]);
+var ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "mr",
+  "mrs",
+  "ms",
+  "dr",
+  "prof",
+  "st",
+  "mt",
+  "ft",
+  "jr",
+  "sr",
+  "inc",
+  "ltd",
+  "co",
+  "corp",
+  "vs",
+  "no"
+]);
+var TRAILING_SEPARATORS = /[\s.,;:\-\u2013\u2014/&([{]+$/;
+function clipAtWordBoundary(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (flat.length <= max) return flat;
+  if (max < 2) return flat.slice(0, Math.max(0, max));
+  const floor = Math.floor(max * (1 - SENTENCE_SHARE));
+  for (let end = max; end > floor; end--) {
+    if (endsSentence(flat, end)) return flat.slice(0, end);
+  }
+  const room = max - 1;
+  const space = flat.lastIndexOf(" ", room);
+  if (space <= 0) return `${flat.slice(0, room)}${ELLIPSIS}`;
+  if (endsSentence(flat, space)) return flat.slice(0, space);
+  const head = flat.slice(0, space).replace(TRAILING_SEPARATORS, "");
+  return `${head || flat.slice(0, room)}${ELLIPSIS}`;
+}
+function endsSentence(flat, end) {
+  if (flat[end] !== " ") return false;
+  let i = end - 1;
+  while (i > 0 && CLOSERS.has(flat[i])) i--;
+  const terminator = flat[i];
+  if (terminator === "!" || terminator === "?") return true;
+  return terminator === "." && !isAbbreviation(flat, i);
+}
+function isAbbreviation(flat, dot) {
+  let start = dot;
+  while (start > 0 && flat[start - 1] !== " ") start--;
+  const token = flat.slice(start, dot).replace(/^[("'[\u201c\u2018]+/, "").toLowerCase();
+  if (token.includes(".") || /^[a-z]$/.test(token)) return true;
+  return ABBREVIATIONS.has(token);
+}
 function sanitizeLlmsPublicSummary(raw) {
   if (raw === null || raw === void 0) return null;
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_PUBLIC_SUMMARY_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_PUBLIC_SUMMARY_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_PUBLIC_SUMMARY_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 8) return null;
@@ -34,9 +84,7 @@ function sanitizeLlmsDisclaimerLine(raw) {
   if (typeof raw !== "string") return null;
   let s = raw.trim().replace(/\s+/g, " ");
   s = s.replace(/[\[\]\r\n]/g, " ").replace(/\s+/g, " ").trim();
-  if (s.length > LLMS_DISCLAIMER_MAX_LENGTH) {
-    s = `${s.slice(0, LLMS_DISCLAIMER_MAX_LENGTH - 1).trimEnd()}\u2026`;
-  }
+  s = clipAtWordBoundary(s, LLMS_DISCLAIMER_MAX_LENGTH);
   if (/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/.test(s)) return null;
   if (/\b\+?\d[\d\s().-]{8,}\b/.test(s)) return null;
   if (s.length < 3) return null;
@@ -94,4 +142,4 @@ function pickManagedLlmSchemaForJsonLd(schema) {
   return Object.keys(out).length ? out : null;
 }
 
-export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, isEmittableReviewNode, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag };
+export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, clipAtWordBoundary, isEmittableReviewNode, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag };

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

package/dist/schema-placeholders.js

@@ -0,0 +1,321 @@
+'use strict';
+
+// src/contracts/schema-placeholders.ts
+var RESERVED_EXAMPLE_DOMAINS = ["example.com", "example.net", "example.org"];
+var RESERVED_EXAMPLE_TLD = "example";
+var PLACEHOLDER_NAMES = /* @__PURE__ */ new Set([
+  "example",
+  "example business",
+  "example company",
+  "example organization",
+  "your business",
+  "your business name",
+  "your company",
+  "your company name",
+  "your organization",
+  "your organization name",
+  "business name",
+  "company name",
+  "organization name",
+  "your name",
+  "lorem ipsum"
+]);
+var NAME_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "legalName",
+  "alternateName",
+  "author",
+  "creator",
+  "publisher",
+  "brand",
+  "provider",
+  "seller",
+  "manufacturer",
+  "organizer",
+  "founder"
+]);
+var PHONE_KEYS = /* @__PURE__ */ new Set(["telephone", "faxNumber"]);
+var URI_TEMPLATE_KEYS = /* @__PURE__ */ new Set(["target", "urlTemplate"]);
+var BODY_TEXT_KEYS = /* @__PURE__ */ new Set(["articleBody"]);
+var ANNOTATION_KEYS = /* @__PURE__ */ new Set(["note", "notes", "_note", "_notes", "_comment", "_comments", "__comment", "$comment"]);
+var STRUCTURAL_KEYS = /* @__PURE__ */ new Set(["@context", "@type", "@id", "position"]);
+var MUSTACHE_SLOT = /\{\{\s*[#^/>&]?\s*[A-Za-z_$][\w$.[\]-]*\s*\}\}/;
+var JSX_EXPRESSION_VALUE = /^\{\s*[A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*|\[[^\]]*\])+[^{}]*\}$/;
+var JSX_MEMBER_IN_TEXT = /\{\s*[A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*)+\s*\}/;
+var BRACKET_SLOT_VALUE = /^\[\s*[A-Za-z][^[\]"{}<>]{0,80}\]$/;
+var BRACKET_SLOT_IN_TEXT = /\[\s*((?:your|insert your|enter your|add your)\s+[^[\]]{1,60}?|(?:(?:business|company|organization|brand|full|first|last|resident|client|customer|author)\s+)?(?:name|phone(?:\s+number)?|telephone|email(?:\s+address)?|(?:street\s+)?address|city|state|zip(?:\s+code)?|postal\s+code|website|url|logo|date))\s*\](?!\()/gi;
+var REPLACE_MARKER = /\bREPLACE(?:_WITH_\w*|_ME\b)/;
+var UPPER_SLOT_VALUE = /^YOUR_[A-Z0-9_]+$/;
+var MAX_DEPTH = 40;
+var MAX_EVIDENCE = 5;
+var EVIDENCE_VALUE_LENGTH = 120;
+function withoutSchemaPlaceholders(value) {
+  const state = { dropped: [], notes: [] };
+  if (value === null || value === void 0) return { value: null, ...state };
+  const result = visitRoot(value, state);
+  return { value: result, ...state };
+}
+function findSchemaPlaceholders(value) {
+  return withoutSchemaPlaceholders(value).dropped;
+}
+var REASON_TEXT = {
+  example_domain: "is on a reserved example domain",
+  placeholder_phone: "is a placeholder phone number",
+  placeholder_name: "is a placeholder name",
+  template_token: "is an unfilled template slot",
+  annotation: "is an AI note, not schema",
+  emptied: "held only placeholders"
+};
+function describeSchemaPlaceholder(node) {
+  const where = `${node.type || "Node"} at ${node.path}`;
+  const first = node.evidence[0];
+  const detail = first ? `${first.key} ${JSON.stringify(first.value)} ${REASON_TEXT[first.reason]}` : REASON_TEXT[node.reasons[0]];
+  return node.reasons.includes("emptied") ? `${where} has nothing real left: ${detail}` : `${where}: ${detail}`;
+}
+function visitRoot(value, state) {
+  if (Array.isArray(value)) {
+    const out = visitArray(value, "$", state, 0, true);
+    return out.removed && out.value.length === 0 ? null : out.value;
+  }
+  if (!isPlainObject(value)) return value;
+  if (isGraphWrapper(value)) {
+    const out = visitContainer(value, "$", state, 0);
+    return out.removedChild && !hasContentBeyond(out.value, /* @__PURE__ */ new Set(["@context"])) ? null : out.value;
+  }
+  const visit = visitNode(value, "$", state, 0);
+  return visit.keep ? visit.value : null;
+}
+function visitNode(node, path, state, depth) {
+  if (isAnnotationOnly(node)) {
+    state.dropped.push({ path, type: null, reasons: ["annotation"], evidence: annotationEvidence(node) });
+    return { keep: false };
+  }
+  const evidence = [];
+  collectEvidence(node, evidence, depth);
+  if (evidence.length) {
+    state.dropped.push({ path, type: typeOf(node), reasons: unique(evidence.map((e) => e.reason)), evidence });
+    return { keep: false };
+  }
+  const droppedMark = state.dropped.length;
+  const notesMark = state.notes.length;
+  const pruned = visitContainer(node, path, state, depth);
+  if (pruned.removedChild && !hasContentBeyond(pruned.value, STRUCTURAL_KEYS)) {
+    const children = state.dropped.splice(droppedMark);
+    state.notes.length = notesMark;
+    state.dropped.push({
+      path,
+      type: typeOf(node),
+      reasons: unique(["emptied", ...children.flatMap((c) => c.reasons)]),
+      evidence: children.flatMap((c) => c.evidence).slice(0, MAX_EVIDENCE)
+    });
+    return { keep: false };
+  }
+  return { keep: true, value: pruned.value };
+}
+function visitContainer(obj, path, state, depth) {
+  if (depth >= MAX_DEPTH) return { value: obj, removedChild: false };
+  let changed = false;
+  let removedChild = false;
+  const out = {};
+  for (const [key, child] of Object.entries(obj)) {
+    if (key === "@context") {
+      out[key] = child;
+      continue;
+    }
+    if (ANNOTATION_KEYS.has(key)) {
+      state.notes.push({ path, key });
+      changed = true;
+      continue;
+    }
+    const childPath = stepKey(path, key);
+    if (Array.isArray(child)) {
+      const pruned = visitArray(child, childPath, state, depth + 1, key === "@graph");
+      if (pruned.removed) removedChild = true;
+      if (pruned.value !== child) changed = true;
+      if (pruned.removed && pruned.value.length === 0) continue;
+      out[key] = pruned.value;
+      continue;
+    }
+    if (isPlainObject(child)) {
+      if (isNestedNode(child)) {
+        const visit = visitNode(child, childPath, state, depth + 1);
+        if (!visit.keep) {
+          changed = true;
+          removedChild = true;
+          continue;
+        }
+        if (visit.value !== child) changed = true;
+        out[key] = visit.value;
+        continue;
+      }
+      const pruned = visitContainer(child, childPath, state, depth + 1);
+      if (pruned.removedChild) removedChild = true;
+      if (pruned.value !== child) changed = true;
+      out[key] = pruned.value;
+      continue;
+    }
+    out[key] = child;
+  }
+  return { value: changed ? out : obj, removedChild };
+}
+function visitArray(items, path, state, depth, units) {
+  if (depth >= MAX_DEPTH) return { value: items, removed: false };
+  let changed = false;
+  let removed = false;
+  const out = [];
+  items.forEach((item, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (Array.isArray(item)) {
+      const pruned = visitArray(item, itemPath, state, depth + 1, units);
+      if (pruned.removed) removed = true;
+      if (pruned.value !== item) changed = true;
+      out.push(pruned.value);
+      return;
+    }
+    if (isPlainObject(item) && (units || isNestedNode(item))) {
+      const visit = visitNode(item, itemPath, state, depth + 1);
+      if (!visit.keep) {
+        changed = true;
+        removed = true;
+        return;
+      }
+      if (visit.value !== item) changed = true;
+      out.push(visit.value);
+      return;
+    }
+    if (isPlainObject(item)) {
+      const pruned = visitContainer(item, itemPath, state, depth + 1);
+      if (pruned.removedChild) removed = true;
+      if (pruned.value !== item) changed = true;
+      out.push(pruned.value);
+      return;
+    }
+    out.push(item);
+  });
+  return { value: changed ? out : items, removed };
+}
+function collectEvidence(holder, out, depth) {
+  for (const [key, value] of Object.entries(holder)) {
+    if (key === "@context" || ANNOTATION_KEYS.has(key)) continue;
+    collectFromValue(holder, key, value, out, depth);
+  }
+}
+function collectFromValue(holder, key, value, out, depth) {
+  if (depth >= MAX_DEPTH || out.length >= MAX_EVIDENCE) return;
+  if (typeof value === "string") {
+    for (const reason of placeholderReasons(key, value, holder)) {
+      if (out.length >= MAX_EVIDENCE) return;
+      out.push({ reason, key, value: cutForLog(value) });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectFromValue(holder, key, item, out, depth + 1);
+    return;
+  }
+  if (isPlainObject(value) && !isNestedNode(value)) collectEvidence(value, out, depth + 1);
+}
+function placeholderReasons(key, raw, holder) {
+  const value = raw.trim();
+  if (!value) return [];
+  const reasons = [];
+  const host = urlHost(value);
+  if (host && isReservedExampleHost(host)) reasons.push("example_domain");
+  if ((PHONE_KEYS.has(key) || /^tel:/i.test(value)) && isPlaceholderPhone(value)) reasons.push("placeholder_phone");
+  if (NAME_KEYS.has(key) && !("value" in holder) && PLACEHOLDER_NAMES.has(normalizeName(value))) {
+    reasons.push("placeholder_name");
+  }
+  if (isTemplateSlot(key, value)) reasons.push("template_token");
+  return reasons;
+}
+function isTemplateSlot(key, value) {
+  if (JSX_EXPRESSION_VALUE.test(value) || BRACKET_SLOT_VALUE.test(value) || UPPER_SLOT_VALUE.test(value)) return true;
+  if (REPLACE_MARKER.test(value)) return true;
+  if (!BODY_TEXT_KEYS.has(key)) {
+    if (MUSTACHE_SLOT.test(value)) return true;
+    for (const match of value.matchAll(BRACKET_SLOT_IN_TEXT)) {
+      if (/^[A-Z]/.test(match[1])) return true;
+    }
+  }
+  return !URI_TEMPLATE_KEYS.has(key) && isUrlOrPath(value) && JSX_MEMBER_IN_TEXT.test(value);
+}
+function urlHost(value) {
+  const mailto = /^mailto:[^@\s?]+@([^?\s#/]+)/i.exec(value);
+  if (mailto) return mailto[1];
+  const url = /^(?:[a-z][a-z0-9+.-]*:)?\/\/(?:[^/?#@\s]*@)?([^/?#:\s]+)/i.exec(value);
+  if (url) return url[1];
+  const email = /^[^\s@/:]+@([^\s@/:?#]+)$/.exec(value);
+  if (email) return email[1];
+  const bare = /^((?:[a-z0-9-]+\.)+[a-z][a-z0-9-]*)\.?(?::\d+)?(?:[/?#]\S*)?$/i.exec(value);
+  return bare ? bare[1] : null;
+}
+function isReservedExampleHost(host) {
+  const h = host.toLowerCase().replace(/\.$/, "");
+  if (h === RESERVED_EXAMPLE_TLD || h.endsWith(`.${RESERVED_EXAMPLE_TLD}`)) return true;
+  return RESERVED_EXAMPLE_DOMAINS.some((domain) => h === domain || h.endsWith(`.${domain}`));
+}
+function isUrlOrPath(value) {
+  return /^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(value) || value.startsWith("/");
+}
+function isPlaceholderPhone(raw) {
+  const value = raw.replace(/^tel:/i, "").trim();
+  if (/^[+\d\s().xX-]+$/.test(value) && (value.match(/x/gi)?.length ?? 0) >= 4) return true;
+  let digits = value.replace(/\D/g, "");
+  if (digits.length === 11 && digits.startsWith("1")) digits = digits.slice(1);
+  if (digits.length >= 7 && /^0+$/.test(digits)) return true;
+  if (digits === "1234567890" || digits === "1234567") return true;
+  const local = digits.length === 10 ? digits.slice(3) : digits.length === 7 ? digits : null;
+  return local !== null && /^55501\d\d$/.test(local);
+}
+function normalizeName(value) {
+  return value.replace(/\s+/g, " ").trim().replace(/[.,]+$/, "").toLowerCase();
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNestedNode(value) {
+  return "@type" in value || "@id" in value || isAnnotationOnly(value);
+}
+function isGraphWrapper(value) {
+  return "@graph" in value && !("@type" in value) && !("@id" in value);
+}
+function isAnnotationOnly(value) {
+  if ("@type" in value || "@id" in value || "@graph" in value) return false;
+  const keys = Object.keys(value).filter((key) => key !== "@context");
+  return keys.length > 0 && keys.every((key) => ANNOTATION_KEYS.has(key));
+}
+function annotationEvidence(node) {
+  return Object.entries(node).filter(([key]) => ANNOTATION_KEYS.has(key)).slice(0, MAX_EVIDENCE).map(([key, value]) => ({
+    reason: "annotation",
+    key,
+    value: cutForLog(typeof value === "string" ? value : JSON.stringify(value) ?? "")
+  }));
+}
+function hasContentBeyond(obj, ignored) {
+  return Object.entries(obj).some(([key, value]) => !ignored.has(key) && hasContent(value));
+}
+function hasContent(value) {
+  if (value === null || value === void 0 || value === "") return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (isPlainObject(value)) return Object.keys(value).length > 0;
+  return true;
+}
+function typeOf(node) {
+  const type = node["@type"];
+  if (typeof type === "string") return type;
+  if (Array.isArray(type)) return type.filter((t) => typeof t === "string").join(",") || null;
+  return null;
+}
+function stepKey(path, key) {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function cutForLog(value) {
+  return value.length > EVIDENCE_VALUE_LENGTH ? `${value.slice(0, EVIDENCE_VALUE_LENGTH)}...` : value;
+}
+
+exports.describeSchemaPlaceholder = describeSchemaPlaceholder;
+exports.findSchemaPlaceholders = findSchemaPlaceholders;
+exports.withoutSchemaPlaceholders = withoutSchemaPlaceholders;

package/dist/schema-placeholders.mjs

@@ -0,0 +1,317 @@
+// src/contracts/schema-placeholders.ts
+var RESERVED_EXAMPLE_DOMAINS = ["example.com", "example.net", "example.org"];
+var RESERVED_EXAMPLE_TLD = "example";
+var PLACEHOLDER_NAMES = /* @__PURE__ */ new Set([
+  "example",
+  "example business",
+  "example company",
+  "example organization",
+  "your business",
+  "your business name",
+  "your company",
+  "your company name",
+  "your organization",
+  "your organization name",
+  "business name",
+  "company name",
+  "organization name",
+  "your name",
+  "lorem ipsum"
+]);
+var NAME_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "legalName",
+  "alternateName",
+  "author",
+  "creator",
+  "publisher",
+  "brand",
+  "provider",
+  "seller",
+  "manufacturer",
+  "organizer",
+  "founder"
+]);
+var PHONE_KEYS = /* @__PURE__ */ new Set(["telephone", "faxNumber"]);
+var URI_TEMPLATE_KEYS = /* @__PURE__ */ new Set(["target", "urlTemplate"]);
+var BODY_TEXT_KEYS = /* @__PURE__ */ new Set(["articleBody"]);
+var ANNOTATION_KEYS = /* @__PURE__ */ new Set(["note", "notes", "_note", "_notes", "_comment", "_comments", "__comment", "$comment"]);
+var STRUCTURAL_KEYS = /* @__PURE__ */ new Set(["@context", "@type", "@id", "position"]);
+var MUSTACHE_SLOT = /\{\{\s*[#^/>&]?\s*[A-Za-z_$][\w$.[\]-]*\s*\}\}/;
+var JSX_EXPRESSION_VALUE = /^\{\s*[A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*|\[[^\]]*\])+[^{}]*\}$/;
+var JSX_MEMBER_IN_TEXT = /\{\s*[A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*)+\s*\}/;
+var BRACKET_SLOT_VALUE = /^\[\s*[A-Za-z][^[\]"{}<>]{0,80}\]$/;
+var BRACKET_SLOT_IN_TEXT = /\[\s*((?:your|insert your|enter your|add your)\s+[^[\]]{1,60}?|(?:(?:business|company|organization|brand|full|first|last|resident|client|customer|author)\s+)?(?:name|phone(?:\s+number)?|telephone|email(?:\s+address)?|(?:street\s+)?address|city|state|zip(?:\s+code)?|postal\s+code|website|url|logo|date))\s*\](?!\()/gi;
+var REPLACE_MARKER = /\bREPLACE(?:_WITH_\w*|_ME\b)/;
+var UPPER_SLOT_VALUE = /^YOUR_[A-Z0-9_]+$/;
+var MAX_DEPTH = 40;
+var MAX_EVIDENCE = 5;
+var EVIDENCE_VALUE_LENGTH = 120;
+function withoutSchemaPlaceholders(value) {
+  const state = { dropped: [], notes: [] };
+  if (value === null || value === void 0) return { value: null, ...state };
+  const result = visitRoot(value, state);
+  return { value: result, ...state };
+}
+function findSchemaPlaceholders(value) {
+  return withoutSchemaPlaceholders(value).dropped;
+}
+var REASON_TEXT = {
+  example_domain: "is on a reserved example domain",
+  placeholder_phone: "is a placeholder phone number",
+  placeholder_name: "is a placeholder name",
+  template_token: "is an unfilled template slot",
+  annotation: "is an AI note, not schema",
+  emptied: "held only placeholders"
+};
+function describeSchemaPlaceholder(node) {
+  const where = `${node.type || "Node"} at ${node.path}`;
+  const first = node.evidence[0];
+  const detail = first ? `${first.key} ${JSON.stringify(first.value)} ${REASON_TEXT[first.reason]}` : REASON_TEXT[node.reasons[0]];
+  return node.reasons.includes("emptied") ? `${where} has nothing real left: ${detail}` : `${where}: ${detail}`;
+}
+function visitRoot(value, state) {
+  if (Array.isArray(value)) {
+    const out = visitArray(value, "$", state, 0, true);
+    return out.removed && out.value.length === 0 ? null : out.value;
+  }
+  if (!isPlainObject(value)) return value;
+  if (isGraphWrapper(value)) {
+    const out = visitContainer(value, "$", state, 0);
+    return out.removedChild && !hasContentBeyond(out.value, /* @__PURE__ */ new Set(["@context"])) ? null : out.value;
+  }
+  const visit = visitNode(value, "$", state, 0);
+  return visit.keep ? visit.value : null;
+}
+function visitNode(node, path, state, depth) {
+  if (isAnnotationOnly(node)) {
+    state.dropped.push({ path, type: null, reasons: ["annotation"], evidence: annotationEvidence(node) });
+    return { keep: false };
+  }
+  const evidence = [];
+  collectEvidence(node, evidence, depth);
+  if (evidence.length) {
+    state.dropped.push({ path, type: typeOf(node), reasons: unique(evidence.map((e) => e.reason)), evidence });
+    return { keep: false };
+  }
+  const droppedMark = state.dropped.length;
+  const notesMark = state.notes.length;
+  const pruned = visitContainer(node, path, state, depth);
+  if (pruned.removedChild && !hasContentBeyond(pruned.value, STRUCTURAL_KEYS)) {
+    const children = state.dropped.splice(droppedMark);
+    state.notes.length = notesMark;
+    state.dropped.push({
+      path,
+      type: typeOf(node),
+      reasons: unique(["emptied", ...children.flatMap((c) => c.reasons)]),
+      evidence: children.flatMap((c) => c.evidence).slice(0, MAX_EVIDENCE)
+    });
+    return { keep: false };
+  }
+  return { keep: true, value: pruned.value };
+}
+function visitContainer(obj, path, state, depth) {
+  if (depth >= MAX_DEPTH) return { value: obj, removedChild: false };
+  let changed = false;
+  let removedChild = false;
+  const out = {};
+  for (const [key, child] of Object.entries(obj)) {
+    if (key === "@context") {
+      out[key] = child;
+      continue;
+    }
+    if (ANNOTATION_KEYS.has(key)) {
+      state.notes.push({ path, key });
+      changed = true;
+      continue;
+    }
+    const childPath = stepKey(path, key);
+    if (Array.isArray(child)) {
+      const pruned = visitArray(child, childPath, state, depth + 1, key === "@graph");
+      if (pruned.removed) removedChild = true;
+      if (pruned.value !== child) changed = true;
+      if (pruned.removed && pruned.value.length === 0) continue;
+      out[key] = pruned.value;
+      continue;
+    }
+    if (isPlainObject(child)) {
+      if (isNestedNode(child)) {
+        const visit = visitNode(child, childPath, state, depth + 1);
+        if (!visit.keep) {
+          changed = true;
+          removedChild = true;
+          continue;
+        }
+        if (visit.value !== child) changed = true;
+        out[key] = visit.value;
+        continue;
+      }
+      const pruned = visitContainer(child, childPath, state, depth + 1);
+      if (pruned.removedChild) removedChild = true;
+      if (pruned.value !== child) changed = true;
+      out[key] = pruned.value;
+      continue;
+    }
+    out[key] = child;
+  }
+  return { value: changed ? out : obj, removedChild };
+}
+function visitArray(items, path, state, depth, units) {
+  if (depth >= MAX_DEPTH) return { value: items, removed: false };
+  let changed = false;
+  let removed = false;
+  const out = [];
+  items.forEach((item, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (Array.isArray(item)) {
+      const pruned = visitArray(item, itemPath, state, depth + 1, units);
+      if (pruned.removed) removed = true;
+      if (pruned.value !== item) changed = true;
+      out.push(pruned.value);
+      return;
+    }
+    if (isPlainObject(item) && (units || isNestedNode(item))) {
+      const visit = visitNode(item, itemPath, state, depth + 1);
+      if (!visit.keep) {
+        changed = true;
+        removed = true;
+        return;
+      }
+      if (visit.value !== item) changed = true;
+      out.push(visit.value);
+      return;
+    }
+    if (isPlainObject(item)) {
+      const pruned = visitContainer(item, itemPath, state, depth + 1);
+      if (pruned.removedChild) removed = true;
+      if (pruned.value !== item) changed = true;
+      out.push(pruned.value);
+      return;
+    }
+    out.push(item);
+  });
+  return { value: changed ? out : items, removed };
+}
+function collectEvidence(holder, out, depth) {
+  for (const [key, value] of Object.entries(holder)) {
+    if (key === "@context" || ANNOTATION_KEYS.has(key)) continue;
+    collectFromValue(holder, key, value, out, depth);
+  }
+}
+function collectFromValue(holder, key, value, out, depth) {
+  if (depth >= MAX_DEPTH || out.length >= MAX_EVIDENCE) return;
+  if (typeof value === "string") {
+    for (const reason of placeholderReasons(key, value, holder)) {
+      if (out.length >= MAX_EVIDENCE) return;
+      out.push({ reason, key, value: cutForLog(value) });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectFromValue(holder, key, item, out, depth + 1);
+    return;
+  }
+  if (isPlainObject(value) && !isNestedNode(value)) collectEvidence(value, out, depth + 1);
+}
+function placeholderReasons(key, raw, holder) {
+  const value = raw.trim();
+  if (!value) return [];
+  const reasons = [];
+  const host = urlHost(value);
+  if (host && isReservedExampleHost(host)) reasons.push("example_domain");
+  if ((PHONE_KEYS.has(key) || /^tel:/i.test(value)) && isPlaceholderPhone(value)) reasons.push("placeholder_phone");
+  if (NAME_KEYS.has(key) && !("value" in holder) && PLACEHOLDER_NAMES.has(normalizeName(value))) {
+    reasons.push("placeholder_name");
+  }
+  if (isTemplateSlot(key, value)) reasons.push("template_token");
+  return reasons;
+}
+function isTemplateSlot(key, value) {
+  if (JSX_EXPRESSION_VALUE.test(value) || BRACKET_SLOT_VALUE.test(value) || UPPER_SLOT_VALUE.test(value)) return true;
+  if (REPLACE_MARKER.test(value)) return true;
+  if (!BODY_TEXT_KEYS.has(key)) {
+    if (MUSTACHE_SLOT.test(value)) return true;
+    for (const match of value.matchAll(BRACKET_SLOT_IN_TEXT)) {
+      if (/^[A-Z]/.test(match[1])) return true;
+    }
+  }
+  return !URI_TEMPLATE_KEYS.has(key) && isUrlOrPath(value) && JSX_MEMBER_IN_TEXT.test(value);
+}
+function urlHost(value) {
+  const mailto = /^mailto:[^@\s?]+@([^?\s#/]+)/i.exec(value);
+  if (mailto) return mailto[1];
+  const url = /^(?:[a-z][a-z0-9+.-]*:)?\/\/(?:[^/?#@\s]*@)?([^/?#:\s]+)/i.exec(value);
+  if (url) return url[1];
+  const email = /^[^\s@/:]+@([^\s@/:?#]+)$/.exec(value);
+  if (email) return email[1];
+  const bare = /^((?:[a-z0-9-]+\.)+[a-z][a-z0-9-]*)\.?(?::\d+)?(?:[/?#]\S*)?$/i.exec(value);
+  return bare ? bare[1] : null;
+}
+function isReservedExampleHost(host) {
+  const h = host.toLowerCase().replace(/\.$/, "");
+  if (h === RESERVED_EXAMPLE_TLD || h.endsWith(`.${RESERVED_EXAMPLE_TLD}`)) return true;
+  return RESERVED_EXAMPLE_DOMAINS.some((domain) => h === domain || h.endsWith(`.${domain}`));
+}
+function isUrlOrPath(value) {
+  return /^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(value) || value.startsWith("/");
+}
+function isPlaceholderPhone(raw) {
+  const value = raw.replace(/^tel:/i, "").trim();
+  if (/^[+\d\s().xX-]+$/.test(value) && (value.match(/x/gi)?.length ?? 0) >= 4) return true;
+  let digits = value.replace(/\D/g, "");
+  if (digits.length === 11 && digits.startsWith("1")) digits = digits.slice(1);
+  if (digits.length >= 7 && /^0+$/.test(digits)) return true;
+  if (digits === "1234567890" || digits === "1234567") return true;
+  const local = digits.length === 10 ? digits.slice(3) : digits.length === 7 ? digits : null;
+  return local !== null && /^55501\d\d$/.test(local);
+}
+function normalizeName(value) {
+  return value.replace(/\s+/g, " ").trim().replace(/[.,]+$/, "").toLowerCase();
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNestedNode(value) {
+  return "@type" in value || "@id" in value || isAnnotationOnly(value);
+}
+function isGraphWrapper(value) {
+  return "@graph" in value && !("@type" in value) && !("@id" in value);
+}
+function isAnnotationOnly(value) {
+  if ("@type" in value || "@id" in value || "@graph" in value) return false;
+  const keys = Object.keys(value).filter((key) => key !== "@context");
+  return keys.length > 0 && keys.every((key) => ANNOTATION_KEYS.has(key));
+}
+function annotationEvidence(node) {
+  return Object.entries(node).filter(([key]) => ANNOTATION_KEYS.has(key)).slice(0, MAX_EVIDENCE).map(([key, value]) => ({
+    reason: "annotation",
+    key,
+    value: cutForLog(typeof value === "string" ? value : JSON.stringify(value) ?? "")
+  }));
+}
+function hasContentBeyond(obj, ignored) {
+  return Object.entries(obj).some(([key, value]) => !ignored.has(key) && hasContent(value));
+}
+function hasContent(value) {
+  if (value === null || value === void 0 || value === "") return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (isPlainObject(value)) return Object.keys(value).length > 0;
+  return true;
+}
+function typeOf(node) {
+  const type = node["@type"];
+  if (typeof type === "string") return type;
+  if (Array.isArray(type)) return type.filter((t) => typeof t === "string").join(",") || null;
+  return null;
+}
+function stepKey(path, key) {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function cutForLog(value) {
+  return value.length > EVIDENCE_VALUE_LENGTH ? `${value.slice(0, EVIDENCE_VALUE_LENGTH)}...` : value;
+}
+
+export { describeSchemaPlaceholder, findSchemaPlaceholders, withoutSchemaPlaceholders };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.3.0",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, and what separates an error page from a page's content. Pure functions, no dependencies.",
+  "version": "2.4.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, and which stored JSON-LD is a template's unfilled placeholder. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -95,6 +95,11 @@
       "import": "./dist/error-page.mjs",
       "require": "./dist/error-page.js"
     },
+    "./schema-placeholders": {
+      "types": "./dist/schema-placeholders.d.ts",
+      "import": "./dist/schema-placeholders.mjs",
+      "require": "./dist/schema-placeholders.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {