@sonordev/contracts 1.0.0 → 2.1.0

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;

package/dist/slots.js

@@ -3,31 +3,215 @@
 var crypto = require('crypto');
 
 // src/contracts/slots.ts
-var SLOTS_CONTRACT_VERSION = 1;
-var SLOT_CONTENT_TYPES = ["text"];
+
+// 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 slotSigningPayload(content) {
-  return `sonor-slot.v${SLOTS_CONTRACT_VERSION}
+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;
+}
+
+// src/contracts/slots.ts
+var SLOTS_CONTRACT_VERSION = 2;
+var SUPPORTED_SLOTS_CONTRACT_VERSIONS = [1, 2];
+function canonicalJson(value) {
+  if (value === null || value === void 0) return "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function slotSigningPayload(content, version = SLOTS_CONTRACT_VERSION) {
+  const head = `sonor-slot.v${version}
 ${content.slot_id}
 ${content.type}
 ${content.content}`;
+  return version === 1 ? head : `${head}
+${canonicalJson(content.value ?? null)}`;
 }
-function signSlotContent(content, apiKey) {
-  return crypto.createHmac("sha256", apiKey).update(slotSigningPayload(content), "utf8").digest("hex");
+function signSlotContent(content, apiKey, version = SLOTS_CONTRACT_VERSION) {
+  return crypto.createHmac("sha256", apiKey).update(slotSigningPayload(content, version), "utf8").digest("hex");
 }
-function verifySlotContent(content, apiKey) {
+function verifySlotContent(content, apiKey, version = SLOTS_CONTRACT_VERSION) {
   if (!content || typeof content !== "object") return false;
   const c = content;
-  if (typeof c.slot_id !== "string" || !isValidSlotId(c.slot_id) || typeof c.content !== "string" || c.content.length === 0 || c.content.length > SLOT_CONTENT_MAX_LENGTH || typeof c.signature !== "string" || !SLOT_CONTENT_TYPES.includes(c.type)) {
+  const allowed = version === 1 ? SLOT_V1_CONTENT_TYPES : SLOT_CONTENT_TYPES;
+  if (typeof c.slot_id !== "string" || !isValidSlotId(c.slot_id) || typeof c.content !== "string" || c.content.length === 0 || c.content.length > SLOT_CONTENT_MAX_LENGTH || typeof c.signature !== "string" || !allowed.includes(c.type)) {
     return false;
   }
+  if (version !== 1) {
+    const check = normalizeSlotValue(c.type, { content: c.content, value: c.value });
+    if (!check.ok || check.content !== c.content) return false;
+    if (canonicalJson(check.value) !== canonicalJson(c.value ?? null)) return false;
+  }
   const expected = signSlotContent(
-    { slot_id: c.slot_id, type: c.type, content: c.content },
-    apiKey
+    { slot_id: c.slot_id, type: c.type, content: c.content, value: c.value ?? null },
+    apiKey,
+    version
   );
   const a = Buffer.from(expected, "utf8");
   const b = Buffer.from(c.signature, "utf8");
@@ -37,8 +221,20 @@ function verifySlotContent(content, apiKey) {
 exports.SLOTS_CONTRACT_VERSION = SLOTS_CONTRACT_VERSION;
 exports.SLOT_CONTENT_MAX_LENGTH = SLOT_CONTENT_MAX_LENGTH;
 exports.SLOT_CONTENT_TYPES = SLOT_CONTENT_TYPES;
+exports.SLOT_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.SUPPORTED_SLOTS_CONTRACT_VERSIONS = SUPPORTED_SLOTS_CONTRACT_VERSIONS;
+exports.canonicalJson = canonicalJson;
+exports.isSafeSlotHref = isSafeSlotHref;
+exports.isSafeSlotImageSrc = isSafeSlotImageSrc;
+exports.isSlotContentType = isSlotContentType;
 exports.isValidSlotId = isValidSlotId;
+exports.normalizeSlotValue = normalizeSlotValue;
+exports.parseSlotRichText = parseSlotRichText;
 exports.signSlotContent = signSlotContent;
+exports.slotListPlainText = slotListPlainText;
 exports.slotSigningPayload = slotSigningPayload;
 exports.verifySlotContent = verifySlotContent;

package/dist/slots.mjs

@@ -1,35 +1,219 @@
 import { createHmac, timingSafeEqual } from 'crypto';
 
 // src/contracts/slots.ts
-var SLOTS_CONTRACT_VERSION = 1;
-var SLOT_CONTENT_TYPES = ["text"];
+
+// 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 slotSigningPayload(content) {
-  return `sonor-slot.v${SLOTS_CONTRACT_VERSION}
+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;
+}
+
+// src/contracts/slots.ts
+var SLOTS_CONTRACT_VERSION = 2;
+var SUPPORTED_SLOTS_CONTRACT_VERSIONS = [1, 2];
+function canonicalJson(value) {
+  if (value === null || value === void 0) return "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function slotSigningPayload(content, version = SLOTS_CONTRACT_VERSION) {
+  const head = `sonor-slot.v${version}
 ${content.slot_id}
 ${content.type}
 ${content.content}`;
+  return version === 1 ? head : `${head}
+${canonicalJson(content.value ?? null)}`;
 }
-function signSlotContent(content, apiKey) {
-  return createHmac("sha256", apiKey).update(slotSigningPayload(content), "utf8").digest("hex");
+function signSlotContent(content, apiKey, version = SLOTS_CONTRACT_VERSION) {
+  return createHmac("sha256", apiKey).update(slotSigningPayload(content, version), "utf8").digest("hex");
 }
-function verifySlotContent(content, apiKey) {
+function verifySlotContent(content, apiKey, version = SLOTS_CONTRACT_VERSION) {
   if (!content || typeof content !== "object") return false;
   const c = content;
-  if (typeof c.slot_id !== "string" || !isValidSlotId(c.slot_id) || typeof c.content !== "string" || c.content.length === 0 || c.content.length > SLOT_CONTENT_MAX_LENGTH || typeof c.signature !== "string" || !SLOT_CONTENT_TYPES.includes(c.type)) {
+  const allowed = version === 1 ? SLOT_V1_CONTENT_TYPES : SLOT_CONTENT_TYPES;
+  if (typeof c.slot_id !== "string" || !isValidSlotId(c.slot_id) || typeof c.content !== "string" || c.content.length === 0 || c.content.length > SLOT_CONTENT_MAX_LENGTH || typeof c.signature !== "string" || !allowed.includes(c.type)) {
     return false;
   }
+  if (version !== 1) {
+    const check = normalizeSlotValue(c.type, { content: c.content, value: c.value });
+    if (!check.ok || check.content !== c.content) return false;
+    if (canonicalJson(check.value) !== canonicalJson(c.value ?? null)) return false;
+  }
   const expected = signSlotContent(
-    { slot_id: c.slot_id, type: c.type, content: c.content },
-    apiKey
+    { slot_id: c.slot_id, type: c.type, content: c.content, value: c.value ?? null },
+    apiKey,
+    version
   );
   const a = Buffer.from(expected, "utf8");
   const b = Buffer.from(c.signature, "utf8");
   return a.length === b.length && timingSafeEqual(a, b);
 }
 
-export { SLOTS_CONTRACT_VERSION, SLOT_CONTENT_MAX_LENGTH, SLOT_CONTENT_TYPES, SLOT_ID_PATTERN, isValidSlotId, signSlotContent, slotSigningPayload, verifySlotContent };
+export { SLOTS_CONTRACT_VERSION, 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, SUPPORTED_SLOTS_CONTRACT_VERSIONS, canonicalJson, isSafeSlotHref, isSafeSlotImageSrc, isSlotContentType, isValidSlotId, normalizeSlotValue, parseSlotRichText, signSlotContent, slotListPlainText, slotSigningPayload, verifySlotContent };

package/dist/voice.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Stands in for every character that isn't prose (code, quotations, link
+ * destinations). It's neither whitespace nor a word character, so a masked
+ * span still separates words and no pattern can match it.
+ */
+export declare const VOICE_MASK = "\u2800";
+export interface VoiceHit {
+    /** UTF-16 offset into the whole string you passed in, never line-relative. */
+    readonly index: number;
+    /** Length of the span to replace. May include a run of spaces or tabs. */
+    readonly length: number;
+    /** The text at [index, index + length) of the string you passed in. */
+    readonly match: string;
+    /** What to put there, first-letter case preserved. Always a straight apostrophe. */
+    readonly suggestion: string;
+}
+export interface VoiceOptions {
+    /**
+     * The text is a heading or title, so one that opens with "What Is" keeps it.
+     * Applies to every line. Pass the heading text, not the Markdown line: `#`
+     * and list markers must already be blanked.
+     */
+    readonly titleLike?: boolean | undefined;
+    /**
+     * Half-open [start, end) UTF-16 ranges to leave alone, computed from the
+     * exact string passed in. Any order, overlaps and touching ranges allowed.
+     * Start is floored and clamped to 0 (so -Infinity means "from the start"),
+     * end is ceiled and clamped to the text length (so Infinity means "to the
+     * end"), and an empty or out-of-text range is ignored. Every protected
+     * character is masked except "\n" and "\r", which stay as they are (a
+     * protected line break still ends its line). A malformed range (NaN, a
+     * non-number, or start after end) or a truthy value that isn't an array
+     * protects the whole text: protection never fails open. A falsy value means
+     * no ranges.
+     */
+    readonly protectedRanges?: ReadonlyArray<readonly [number, number]> | undefined;
+}
+/**
+ * Full forms the house voice contracts ("do not" -> "don't"). Read one line at
+ * a time: split on "\n"; a "\r" right before it, or at the very end of the
+ * text, ends the line with it; any other "\r" is text.
+ * Sorted by index, never overlapping, [] for ''.
+ */
+export declare function findUncontracted(text: string, options?: VoiceOptions): VoiceHit[];
+/**
+ * `text` with every findUncontracted hit applied. Returns `text` itself when
+ * nothing applies, and for anything that isn't a string. Protected characters
+ * are never rewritten.
+ */
+export declare function contractText(text: string, options?: VoiceOptions): string;
+/**
+ * Contractions a question-form heading or FAQ question must expand
+ * ("What's" -> "What is"). Sorted by index, never overlapping. `titleLike` is
+ * not part of this direction.
+ */
+export declare function findContracted(text: string, options?: Pick<VoiceOptions, 'protectedRanges'>): VoiceHit[];