@sonordev/contracts 1.0.0 → 2.0.0

package/dist/slot-content.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @sonordev/contracts/slot-content — what a managed slot may contain.
+ *
+ * The pure half of the slots contract: content types, value validation
+ * (normalizeSlotValue), safe links, and the rich-text subset parser. No
+ * crypto, so the dashboard can import it in the browser to validate and
+ * preview exactly what sonor-api will accept and site-kit will render.
+ * `@sonordev/contracts/slots` re-exports all of it next to the signing.
+ */
+/**
+ * - `text`: plain text, rendered escaped.
+ * - `rich`: the restricted markdown subset parseSlotRichText understands,
+ *   rendered to elements, never HTML.
+ * - `link`: `{ label, href }`.
+ * - `list`: `{ items: [{ title?, body?, href?, image? }] }`.
+ */
+export type SlotContentType = 'text' | 'rich' | 'link' | 'list';
+export declare const SLOT_CONTENT_TYPES: readonly SlotContentType[];
+/** What a v1 client can render. */
+export declare const SLOT_V1_CONTENT_TYPES: readonly SlotContentType[];
+/** Hard cap on managed content length; longer payloads are rejected → fallback. */
+export declare const SLOT_CONTENT_MAX_LENGTH = 10000;
+/** Caps for structured values. */
+export declare const SLOT_LIST_MAX_ITEMS = 50;
+export declare const SLOT_FIELD_MAX_LENGTH = 2000;
+export declare const SLOT_HREF_MAX_LENGTH = 2048;
+/** Slot ids: lowercase, page-scoped by convention, e.g. "home-hero-headline". */
+export declare const SLOT_ID_PATTERN: RegExp;
+export interface SlotLinkValue {
+    label: string;
+    href: string;
+}
+export interface SlotListImage {
+    /** https only. */
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+}
+export interface SlotListItem {
+    title?: string;
+    /** Plain text. */
+    body?: string;
+    href?: string;
+    image?: SlotListImage;
+}
+export interface SlotListValue {
+    items: SlotListItem[];
+}
+/** The structured value for `link` and `list`; `text` and `rich` carry none. */
+export type SlotValue = SlotLinkValue | SlotListValue;
+export declare function isValidSlotId(id: string): boolean;
+export declare function isSlotContentType(type: unknown): type is SlotContentType;
+/** Links a slot may carry: https, http, mailto, tel, #anchor, or a root-relative path. */
+export declare function isSafeSlotHref(href: unknown): href is string;
+/** Images a list item may carry: https only. */
+export declare function isSafeSlotImageSrc(src: unknown): src is string;
+export type SlotValueResult = {
+    ok: true;
+    content: string;
+    value: SlotValue | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate and normalize what an editor (or Signal) submits for a slot of
+ * `type`, returning the canonical `content` + `value` to store and sign.
+ * The single rule for "what a valid slot of this type is": sonor-api runs it
+ * on every write and verifySlotContent re-runs it on every read.
+ */
+export declare function normalizeSlotValue(type: SlotContentType, input: {
+    content?: unknown;
+    value?: unknown;
+}): SlotValueResult;
+/** The plain-text rendering of a list: its titles (or bodies, or alts), one per line. */
+export declare function slotListPlainText(items: SlotListItem[]): string;
+export type SlotRichInline = {
+    t: 'text';
+    v: string;
+} | {
+    t: 'strong';
+    c: SlotRichInline[];
+} | {
+    t: 'em';
+    c: SlotRichInline[];
+} | {
+    t: 'link';
+    href: string;
+    c: SlotRichInline[];
+} | {
+    t: 'br';
+};
+export type SlotRichBlock = {
+    t: 'p';
+    c: SlotRichInline[];
+} | {
+    t: 'ul';
+    items: SlotRichInline[][];
+} | {
+    t: 'ol';
+    items: SlotRichInline[][];
+};
+/**
+ * Parse the rich-text subset into a tiny AST: paragraphs (blank-line
+ * separated; single newlines become line breaks), `-`/`*` and `1.` lists,
+ * `**bold**`, `*italic*` / `_italic_`, and `[text](href)` with a safe href.
+ * Anything else is literal text. No HTML, ever: a renderer maps these nodes
+ * to elements, so there's nothing to sanitize.
+ */
+export declare function parseSlotRichText(markdown: string): SlotRichBlock[];

package/dist/slot-content.js

@@ -0,0 +1,184 @@
+'use strict';
+
+// src/contracts/slot-content.ts
+var SLOT_CONTENT_TYPES = ["text", "rich", "link", "list"];
+var SLOT_V1_CONTENT_TYPES = ["text"];
+var SLOT_CONTENT_MAX_LENGTH = 1e4;
+var SLOT_LIST_MAX_ITEMS = 50;
+var SLOT_FIELD_MAX_LENGTH = 2e3;
+var SLOT_HREF_MAX_LENGTH = 2048;
+var SLOT_ID_PATTERN = /^[a-z0-9][a-z0-9-_.:]{0,127}$/;
+function isValidSlotId(id) {
+  return SLOT_ID_PATTERN.test(id);
+}
+function isSlotContentType(type) {
+  return typeof type === "string" && SLOT_CONTENT_TYPES.includes(type);
+}
+function isSafeSlotHref(href) {
+  if (typeof href !== "string") return false;
+  const h = href.trim();
+  if (!h || h.length > SLOT_HREF_MAX_LENGTH) return false;
+  if (h.startsWith("/")) return !h.startsWith("//") && !/\s/.test(h);
+  if (h.startsWith("#")) return !/\s/.test(h);
+  return /^(https?:\/\/[^\s]+|mailto:[^\s]+|tel:[+\d][\d\s().-]*)$/i.test(h);
+}
+function isSafeSlotImageSrc(src) {
+  return typeof src === "string" && src.length <= SLOT_HREF_MAX_LENGTH && /^https:\/\/[^\s]+$/i.test(src);
+}
+function cleanField(v) {
+  if (typeof v !== "string") return void 0;
+  const t = v.trim();
+  return t ? t.slice(0, SLOT_FIELD_MAX_LENGTH) : void 0;
+}
+function normalizeSlotValue(type, input) {
+  if (type === "text" || type === "rich") {
+    const content = typeof input.content === "string" ? input.content.trim() : "";
+    if (!content) return { ok: false, error: `${type} slot needs non-empty content` };
+    if (content.length > SLOT_CONTENT_MAX_LENGTH) {
+      return { ok: false, error: `content is over ${SLOT_CONTENT_MAX_LENGTH} characters` };
+    }
+    return { ok: true, content, value: null };
+  }
+  const raw = input.value ?? null;
+  if (!raw || typeof raw !== "object") return { ok: false, error: `${type} slot needs a value` };
+  if (type === "link") {
+    const label = cleanField(raw.label);
+    const href = typeof raw.href === "string" ? raw.href.trim() : "";
+    if (!label) return { ok: false, error: "link needs a label" };
+    if (!isSafeSlotHref(href)) {
+      return { ok: false, error: "link href must be https, http, mailto, tel, #anchor or a /path" };
+    }
+    return { ok: true, content: label, value: { label, href } };
+  }
+  if (type !== "list") return { ok: false, error: `unknown slot type ${String(type)}` };
+  const itemsIn = Array.isArray(raw.items) ? raw.items : null;
+  if (!itemsIn) return { ok: false, error: "list needs items" };
+  if (itemsIn.length > SLOT_LIST_MAX_ITEMS) {
+    return { ok: false, error: `list is over ${SLOT_LIST_MAX_ITEMS} items` };
+  }
+  const items = [];
+  for (const [i, it] of itemsIn.entries()) {
+    if (!it || typeof it !== "object") return { ok: false, error: `item ${i + 1} isn't an object` };
+    const src = it;
+    const item = {};
+    const title = cleanField(src.title);
+    const body = cleanField(src.body);
+    if (title) item.title = title;
+    if (body) item.body = body;
+    if (src.href !== void 0 && src.href !== null && src.href !== "") {
+      if (!isSafeSlotHref(src.href)) return { ok: false, error: `item ${i + 1} has an unsafe href` };
+      item.href = src.href.trim();
+    }
+    if (src.image !== void 0 && src.image !== null) {
+      const img = src.image;
+      if (!isSafeSlotImageSrc(img.src)) return { ok: false, error: `item ${i + 1} image needs an https src` };
+      const alt = typeof img.alt === "string" ? img.alt.trim().slice(0, SLOT_FIELD_MAX_LENGTH) : "";
+      const image = { src: img.src, alt };
+      if (Number.isInteger(img.width) && img.width > 0) image.width = img.width;
+      if (Number.isInteger(img.height) && img.height > 0) image.height = img.height;
+      item.image = image;
+    }
+    if (!item.title && !item.body && !item.image) {
+      return { ok: false, error: `item ${i + 1} needs a title, body or image` };
+    }
+    items.push(item);
+  }
+  if (items.length === 0) return { ok: false, error: "list needs at least one item" };
+  return { ok: true, content: slotListPlainText(items), value: { items } };
+}
+function slotListPlainText(items) {
+  const text = items.map((it) => it.title ?? it.body ?? it.image?.alt ?? "").filter(Boolean).join("\n");
+  return (text || `${items.length} items`).slice(0, SLOT_CONTENT_MAX_LENGTH);
+}
+var UL_ITEM = /^\s*[-*]\s+(.*)$/;
+var OL_ITEM = /^\s*\d+[.)]\s+(.*)$/;
+var MAX_INLINE_DEPTH = 4;
+function parseSlotRichText(markdown) {
+  const blocks = [];
+  const chunks = markdown.replace(/\r\n?/g, "\n").split(/\n\s*\n/);
+  for (const chunk of chunks) {
+    const lines = chunk.split("\n").filter((l) => l.trim() !== "");
+    if (lines.length === 0) continue;
+    if (lines.every((l) => UL_ITEM.test(l))) {
+      blocks.push({ t: "ul", items: lines.map((l) => parseInline(UL_ITEM.exec(l)[1])) });
+    } else if (lines.every((l) => OL_ITEM.test(l))) {
+      blocks.push({ t: "ol", items: lines.map((l) => parseInline(OL_ITEM.exec(l)[1])) });
+    } else {
+      const c = [];
+      lines.forEach((line, i) => {
+        if (i > 0) c.push({ t: "br" });
+        c.push(...parseInline(line.trim()));
+      });
+      blocks.push({ t: "p", c });
+    }
+  }
+  return blocks;
+}
+function parseInline(src, depth = 0) {
+  const out = [];
+  let text = "";
+  const flush = () => {
+    if (text) out.push({ t: "text", v: text });
+    text = "";
+  };
+  const nest = depth < MAX_INLINE_DEPTH;
+  let i = 0;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === "\\" && i + 1 < src.length && /[\\*_[\]()]/.test(src[i + 1])) {
+      text += src[i + 1];
+      i += 2;
+      continue;
+    }
+    if (nest && src.startsWith("**", i)) {
+      const end = src.indexOf("**", i + 2);
+      if (end > i + 2) {
+        flush();
+        out.push({ t: "strong", c: parseInline(src.slice(i + 2, end), depth + 1) });
+        i = end + 2;
+        continue;
+      }
+    }
+    if (nest && (ch === "*" || ch === "_")) {
+      const end = src.indexOf(ch, i + 1);
+      if (end > i + 1 && src[i + 1] !== " " && src[end - 1] !== " ") {
+        flush();
+        out.push({ t: "em", c: parseInline(src.slice(i + 1, end), depth + 1) });
+        i = end + 1;
+        continue;
+      }
+    }
+    if (nest && ch === "[") {
+      const close = src.indexOf("](", i + 1);
+      const end = close === -1 ? -1 : src.indexOf(")", close + 2);
+      if (close > i + 1 && end > close + 2) {
+        const href = src.slice(close + 2, end).trim();
+        if (isSafeSlotHref(href)) {
+          flush();
+          out.push({ t: "link", href, c: parseInline(src.slice(i + 1, close), depth + 1) });
+          i = end + 1;
+          continue;
+        }
+      }
+    }
+    text += ch;
+    i += 1;
+  }
+  flush();
+  return out;
+}
+
+exports.SLOT_CONTENT_MAX_LENGTH = SLOT_CONTENT_MAX_LENGTH;
+exports.SLOT_CONTENT_TYPES = SLOT_CONTENT_TYPES;
+exports.SLOT_FIELD_MAX_LENGTH = SLOT_FIELD_MAX_LENGTH;
+exports.SLOT_HREF_MAX_LENGTH = SLOT_HREF_MAX_LENGTH;
+exports.SLOT_ID_PATTERN = SLOT_ID_PATTERN;
+exports.SLOT_LIST_MAX_ITEMS = SLOT_LIST_MAX_ITEMS;
+exports.SLOT_V1_CONTENT_TYPES = SLOT_V1_CONTENT_TYPES;
+exports.isSafeSlotHref = isSafeSlotHref;
+exports.isSafeSlotImageSrc = isSafeSlotImageSrc;
+exports.isSlotContentType = isSlotContentType;
+exports.isValidSlotId = isValidSlotId;
+exports.normalizeSlotValue = normalizeSlotValue;
+exports.parseSlotRichText = parseSlotRichText;
+exports.slotListPlainText = slotListPlainText;

package/dist/slot-content.mjs

@@ -0,0 +1,169 @@
+// src/contracts/slot-content.ts
+var SLOT_CONTENT_TYPES = ["text", "rich", "link", "list"];
+var SLOT_V1_CONTENT_TYPES = ["text"];
+var SLOT_CONTENT_MAX_LENGTH = 1e4;
+var SLOT_LIST_MAX_ITEMS = 50;
+var SLOT_FIELD_MAX_LENGTH = 2e3;
+var SLOT_HREF_MAX_LENGTH = 2048;
+var SLOT_ID_PATTERN = /^[a-z0-9][a-z0-9-_.:]{0,127}$/;
+function isValidSlotId(id) {
+  return SLOT_ID_PATTERN.test(id);
+}
+function isSlotContentType(type) {
+  return typeof type === "string" && SLOT_CONTENT_TYPES.includes(type);
+}
+function isSafeSlotHref(href) {
+  if (typeof href !== "string") return false;
+  const h = href.trim();
+  if (!h || h.length > SLOT_HREF_MAX_LENGTH) return false;
+  if (h.startsWith("/")) return !h.startsWith("//") && !/\s/.test(h);
+  if (h.startsWith("#")) return !/\s/.test(h);
+  return /^(https?:\/\/[^\s]+|mailto:[^\s]+|tel:[+\d][\d\s().-]*)$/i.test(h);
+}
+function isSafeSlotImageSrc(src) {
+  return typeof src === "string" && src.length <= SLOT_HREF_MAX_LENGTH && /^https:\/\/[^\s]+$/i.test(src);
+}
+function cleanField(v) {
+  if (typeof v !== "string") return void 0;
+  const t = v.trim();
+  return t ? t.slice(0, SLOT_FIELD_MAX_LENGTH) : void 0;
+}
+function normalizeSlotValue(type, input) {
+  if (type === "text" || type === "rich") {
+    const content = typeof input.content === "string" ? input.content.trim() : "";
+    if (!content) return { ok: false, error: `${type} slot needs non-empty content` };
+    if (content.length > SLOT_CONTENT_MAX_LENGTH) {
+      return { ok: false, error: `content is over ${SLOT_CONTENT_MAX_LENGTH} characters` };
+    }
+    return { ok: true, content, value: null };
+  }
+  const raw = input.value ?? null;
+  if (!raw || typeof raw !== "object") return { ok: false, error: `${type} slot needs a value` };
+  if (type === "link") {
+    const label = cleanField(raw.label);
+    const href = typeof raw.href === "string" ? raw.href.trim() : "";
+    if (!label) return { ok: false, error: "link needs a label" };
+    if (!isSafeSlotHref(href)) {
+      return { ok: false, error: "link href must be https, http, mailto, tel, #anchor or a /path" };
+    }
+    return { ok: true, content: label, value: { label, href } };
+  }
+  if (type !== "list") return { ok: false, error: `unknown slot type ${String(type)}` };
+  const itemsIn = Array.isArray(raw.items) ? raw.items : null;
+  if (!itemsIn) return { ok: false, error: "list needs items" };
+  if (itemsIn.length > SLOT_LIST_MAX_ITEMS) {
+    return { ok: false, error: `list is over ${SLOT_LIST_MAX_ITEMS} items` };
+  }
+  const items = [];
+  for (const [i, it] of itemsIn.entries()) {
+    if (!it || typeof it !== "object") return { ok: false, error: `item ${i + 1} isn't an object` };
+    const src = it;
+    const item = {};
+    const title = cleanField(src.title);
+    const body = cleanField(src.body);
+    if (title) item.title = title;
+    if (body) item.body = body;
+    if (src.href !== void 0 && src.href !== null && src.href !== "") {
+      if (!isSafeSlotHref(src.href)) return { ok: false, error: `item ${i + 1} has an unsafe href` };
+      item.href = src.href.trim();
+    }
+    if (src.image !== void 0 && src.image !== null) {
+      const img = src.image;
+      if (!isSafeSlotImageSrc(img.src)) return { ok: false, error: `item ${i + 1} image needs an https src` };
+      const alt = typeof img.alt === "string" ? img.alt.trim().slice(0, SLOT_FIELD_MAX_LENGTH) : "";
+      const image = { src: img.src, alt };
+      if (Number.isInteger(img.width) && img.width > 0) image.width = img.width;
+      if (Number.isInteger(img.height) && img.height > 0) image.height = img.height;
+      item.image = image;
+    }
+    if (!item.title && !item.body && !item.image) {
+      return { ok: false, error: `item ${i + 1} needs a title, body or image` };
+    }
+    items.push(item);
+  }
+  if (items.length === 0) return { ok: false, error: "list needs at least one item" };
+  return { ok: true, content: slotListPlainText(items), value: { items } };
+}
+function slotListPlainText(items) {
+  const text = items.map((it) => it.title ?? it.body ?? it.image?.alt ?? "").filter(Boolean).join("\n");
+  return (text || `${items.length} items`).slice(0, SLOT_CONTENT_MAX_LENGTH);
+}
+var UL_ITEM = /^\s*[-*]\s+(.*)$/;
+var OL_ITEM = /^\s*\d+[.)]\s+(.*)$/;
+var MAX_INLINE_DEPTH = 4;
+function parseSlotRichText(markdown) {
+  const blocks = [];
+  const chunks = markdown.replace(/\r\n?/g, "\n").split(/\n\s*\n/);
+  for (const chunk of chunks) {
+    const lines = chunk.split("\n").filter((l) => l.trim() !== "");
+    if (lines.length === 0) continue;
+    if (lines.every((l) => UL_ITEM.test(l))) {
+      blocks.push({ t: "ul", items: lines.map((l) => parseInline(UL_ITEM.exec(l)[1])) });
+    } else if (lines.every((l) => OL_ITEM.test(l))) {
+      blocks.push({ t: "ol", items: lines.map((l) => parseInline(OL_ITEM.exec(l)[1])) });
+    } else {
+      const c = [];
+      lines.forEach((line, i) => {
+        if (i > 0) c.push({ t: "br" });
+        c.push(...parseInline(line.trim()));
+      });
+      blocks.push({ t: "p", c });
+    }
+  }
+  return blocks;
+}
+function parseInline(src, depth = 0) {
+  const out = [];
+  let text = "";
+  const flush = () => {
+    if (text) out.push({ t: "text", v: text });
+    text = "";
+  };
+  const nest = depth < MAX_INLINE_DEPTH;
+  let i = 0;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === "\\" && i + 1 < src.length && /[\\*_[\]()]/.test(src[i + 1])) {
+      text += src[i + 1];
+      i += 2;
+      continue;
+    }
+    if (nest && src.startsWith("**", i)) {
+      const end = src.indexOf("**", i + 2);
+      if (end > i + 2) {
+        flush();
+        out.push({ t: "strong", c: parseInline(src.slice(i + 2, end), depth + 1) });
+        i = end + 2;
+        continue;
+      }
+    }
+    if (nest && (ch === "*" || ch === "_")) {
+      const end = src.indexOf(ch, i + 1);
+      if (end > i + 1 && src[i + 1] !== " " && src[end - 1] !== " ") {
+        flush();
+        out.push({ t: "em", c: parseInline(src.slice(i + 1, end), depth + 1) });
+        i = end + 1;
+        continue;
+      }
+    }
+    if (nest && ch === "[") {
+      const close = src.indexOf("](", i + 1);
+      const end = close === -1 ? -1 : src.indexOf(")", close + 2);
+      if (close > i + 1 && end > close + 2) {
+        const href = src.slice(close + 2, end).trim();
+        if (isSafeSlotHref(href)) {
+          flush();
+          out.push({ t: "link", href, c: parseInline(src.slice(i + 1, close), depth + 1) });
+          i = end + 1;
+          continue;
+        }
+      }
+    }
+    text += ch;
+    i += 1;
+  }
+  flush();
+  return out;
+}
+
+export { SLOT_CONTENT_MAX_LENGTH, SLOT_CONTENT_TYPES, SLOT_FIELD_MAX_LENGTH, SLOT_HREF_MAX_LENGTH, SLOT_ID_PATTERN, SLOT_LIST_MAX_ITEMS, SLOT_V1_CONTENT_TYPES, isSafeSlotHref, isSafeSlotImageSrc, isSlotContentType, isValidSlotId, normalizeSlotValue, parseSlotRichText, slotListPlainText };

package/dist/slots.d.ts

@@ -1,33 +1,37 @@
 /**
- * @sonordev/contracts/slots — Managed Slots wire contract (v1)
+ * @sonordev/contracts/slots — Managed Slots wire contract (v2)
  *
- * 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`.
+ * Single source of truth for the slot payload shape, value validation, the
+ * rich-text subset, and content signing, shared by site-kit (verify + render),
+ * sonor-api (validate + sign) and the dashboard (preview). 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.
+ * end to end. See docs/SITE-KIT-3.0-SPEC-SLOTS.md and docs/WEBSITE-CMS.md.
+ *
+ * v1 (site-kit ≤ 7.0) is plain text only. v2 adds rich text, links and lists,
+ * and signs the structured value too. sonor-api serves both: a v1 request gets
+ * text slots signed the v1 way and null for everything else.
  */
-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;
+import { type SlotContentType, type SlotValue } from './slot-content';
+export * from './slot-content';
+/** The version this package speaks. Bump on breaking payload changes. */
+export declare const SLOTS_CONTRACT_VERSION = 2;
+/** Versions sonor-api still serves. */
+export declare const SUPPORTED_SLOTS_CONTRACT_VERSIONS: readonly number[];
 export interface SlotContent {
     slot_id: string;
     type: SlotContentType;
-    /** The managed text. Rendered escaped — never as HTML. */
+    /**
+     * Always a non-empty plain-text rendering: the text (text), the markdown
+     * (rich), the label (link), the item titles (list). Rendered escaped for
+     * `text`; the Copy Evidence Loop and Signal read it for every type.
+     */
     content: string;
+    /** Structured value for `link` / `list` (v2). */
+    value?: SlotValue | null;
     /** Forward-compat: experiment/personalization variant that produced this content. */
     variant_id?: string | null;
     experiment_id?: string | null;
@@ -38,6 +42,8 @@ export interface SlotContent {
 }
 export interface SlotResolveRequestEntry {
     id: string;
+    /** v2: what the site renders this slot as. Absent = 'text' (v1). */
+    type?: SlotContentType;
     /**
      * The developer's current static text for this slot (when statically
      * extractable). Stored as `fallback_text` on registration so the dashboard
@@ -45,6 +51,8 @@ export interface SlotResolveRequestEntry {
      * the API anywhere — display + drafting context only.
      */
     fallback?: string;
+    /** v2: the structured fallback (a link or list the site ships), for the editor. */
+    fallback_value?: SlotValue;
     /**
      * 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
@@ -62,20 +70,26 @@ export interface SlotsResolveResponse {
     contract_version: number;
     slots: Record<string, SlotContent | null>;
 }
-export declare function isValidSlotId(id: string): boolean;
+/** JSON with object keys sorted at every level, so both sides sign the same bytes. */
+export declare function canonicalJson(value: unknown): string;
+type Signable = Pick<SlotContent, 'slot_id' | 'type' | 'content'> & {
+    value?: SlotValue | null;
+};
 /**
  * Canonical string both sides sign/verify. Exported separately from the HMAC
  * helpers so an edge-runtime resolver can reproduce it with WebCrypto.
+ * `version` 1 is the pre-v2 text-only form, kept byte-for-byte so sites on
+ * older site-kit keep verifying.
  */
-export declare function slotSigningPayload(content: Pick<SlotContent, 'slot_id' | 'type' | 'content'>): string;
+export declare function slotSigningPayload(content: Signable, version?: number): 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;
+export declare function signSlotContent(content: Signable, apiKey: string, version?: number): 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.
+ * Returns true only when the payload is well-formed for its type, within
+ * limits, and the signature matches the project API key. Constant-time.
  */
-export declare function verifySlotContent(content: unknown, apiKey: string): content is SlotContent;
+export declare function verifySlotContent(content: unknown, apiKey: string, version?: number): content is SlotContent;