@sonordev/contracts 1.0.0

package/dist/website.mjs

@@ -0,0 +1,355 @@
+// src/contracts/color.ts
+var HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+function channel(v) {
+  const c = v / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance({ r, g, b }) {
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+function hexToRgb(hex) {
+  if (!HEX_COLOR.test(hex)) return null;
+  let c = hex.slice(1);
+  if (c.length <= 4) c = c.split("").map((ch) => ch + ch).join("");
+  if (c.length === 8 && c.slice(6) === "00") return null;
+  return {
+    r: parseInt(c.slice(0, 2), 16),
+    g: parseInt(c.slice(2, 4), 16),
+    b: parseInt(c.slice(4, 6), 16)
+  };
+}
+function hslToRgb(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return { r: Math.round(f(0) * 255), g: Math.round(f(8) * 255), b: Math.round(f(4) * 255) };
+}
+function colorArgs(inner) {
+  const [main, alpha] = inner.split("/");
+  const parts = main.split(/[\s,]+/).filter(Boolean);
+  if (alpha === void 0 && parts.length === 4) return { parts: parts.slice(0, 3), alpha: parts[3] };
+  return { parts, alpha: alpha?.trim() };
+}
+function isTransparentAlpha(alpha) {
+  if (!alpha) return false;
+  const n = alpha.endsWith("%") ? parseFloat(alpha) / 100 : parseFloat(alpha);
+  return n === 0;
+}
+function colorFunction(v) {
+  const fn = v.match(/^([a-z]+)\((.*)\)$/);
+  if (!fn) return null;
+  const { parts, alpha } = colorArgs(fn[2]);
+  if (isTransparentAlpha(alpha) || parts.length < 3) return null;
+  return { name: fn[1], parts };
+}
+var num = (p, scale) => p.endsWith("%") ? parseFloat(p) / 100 * scale : parseFloat(p);
+function parseColor(value) {
+  const v = value.trim().toLowerCase();
+  if (!v || v === "transparent") return null;
+  if (v === "white") return { r: 255, g: 255, b: 255 };
+  if (v === "black") return { r: 0, g: 0, b: 0 };
+  if (v.startsWith("#")) return hexToRgb(v);
+  const fn = colorFunction(v);
+  if (fn) {
+    const { name, parts } = fn;
+    if (name === "rgb" || name === "rgba") {
+      const [r, g, b] = parts.map((p) => num(p, 255));
+      return [r, g, b].some(Number.isNaN) ? null : { r, g, b };
+    }
+    if (name === "hsl" || name === "hsla") {
+      const h = parseFloat(parts[0]);
+      const s = num(parts[1], 1);
+      const l = num(parts[2], 1);
+      return [h, s, l].some(Number.isNaN) ? null : hslToRgb(h, s, l);
+    }
+    return null;
+  }
+  const triple = v.match(/^(-?[\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%$/);
+  if (triple) return hslToRgb(parseFloat(triple[1]), parseFloat(triple[2]) / 100, parseFloat(triple[3]) / 100);
+  return null;
+}
+
+// src/contracts/website.ts
+var DESIGN_TOKENS_VERSION = 1;
+var HEX = (rgb) => `#${[rgb.r, rgb.g, rgb.b].map((c) => Math.max(0, Math.min(255, Math.round(c))).toString(16).padStart(2, "0")).join("")}`;
+function toHexColor(value) {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  const inner = v.match(/^(?:rgba?|hsla?)\(([^)]*)\)$/i)?.[1];
+  if (inner) {
+    const alpha = inner.includes("/") ? inner.split("/")[1]?.trim() : inner.split(",")[3]?.trim();
+    if (alpha && (alpha.endsWith("%") ? parseFloat(alpha) / 100 : parseFloat(alpha)) < 0.5) return null;
+  }
+  if (/^#[0-9a-f]{8}$/i.test(v) && parseInt(v.slice(7, 9), 16) < 128) return null;
+  const rgb = parseColor(v);
+  return rgb ? HEX(rgb) : null;
+}
+var luminanceOf = (hex) => {
+  const rgb = parseColor(hex);
+  return rgb ? relativeLuminance(rgb) : 1;
+};
+function mixHex(a, b, t) {
+  const x = parseColor(a);
+  const y = parseColor(b);
+  if (!x || !y) return a;
+  return HEX({ r: x.r + (y.r - x.r) * t, g: x.g + (y.g - x.g) * t, b: x.b + (y.b - x.b) * t });
+}
+function mutedFor(text, background) {
+  const bg = luminanceOf(background);
+  for (const t of [0.4, 0.3, 0.2, 0.1]) {
+    const m = mixHex(text, background, t);
+    const l = luminanceOf(m);
+    if ((Math.max(l, bg) + 0.05) / (Math.min(l, bg) + 0.05) >= 4.5) return m;
+  }
+  return text;
+}
+function readableOn(hex) {
+  const lum = luminanceOf(hex);
+  const onWhite = 1.05 / (lum + 0.05);
+  const onDark = (lum + 0.05) / (luminanceOf("#111827") + 0.05);
+  return onWhite >= onDark ? "#ffffff" : "#111827";
+}
+function fontStack(value) {
+  if (typeof value !== "string") return null;
+  const clean = value.replace(/[^A-Za-z0-9 ,'"_-]/g, "").replace(/\s+/g, " ").trim().slice(0, 200);
+  return clean && /[A-Za-z]/.test(clean) ? clean : null;
+}
+function radiusLength(value) {
+  if (value === 0 || value === "0") return "0px";
+  if (typeof value !== "string") return null;
+  const m = value.trim().match(/^(\d+(?:\.\d+)?)(px|rem|em)$/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const max = m[2] === "px" ? 64 : 4;
+  return `${Math.min(n, max)}${m[2]}`;
+}
+var FALLBACK_FONT = 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
+function normalizeDesignTokens(input) {
+  if (!input || typeof input !== "object") return null;
+  const raw = input;
+  const c = raw.colors ?? {};
+  const background = toHexColor(c.background);
+  const text = toHexColor(c.text);
+  const primary = toHexColor(c.primary);
+  if (!background || !text || !primary) return null;
+  const scheme = luminanceOf(background) < 0.179 ? "dark" : "light";
+  const fonts = raw.fonts ?? {};
+  const radius = raw.radius ?? {};
+  const button = raw.button ?? {};
+  const body = fontStack(fonts.body) ?? FALLBACK_FONT;
+  const control = radiusLength(radius.control) ?? "8px";
+  return {
+    version: DESIGN_TOKENS_VERSION,
+    colors: {
+      background,
+      surface: toHexColor(c.surface) ?? background,
+      text,
+      muted: toHexColor(c.muted) ?? mutedFor(text, background),
+      primary,
+      onPrimary: toHexColor(c.onPrimary) ?? readableOn(primary),
+      border: toHexColor(c.border) ?? (scheme === "dark" ? "#374151" : "#e5e7eb")
+    },
+    fonts: { body, heading: fontStack(fonts.heading) ?? body },
+    // A pill site's control radius would make a pill-shaped popup; a card it
+    // didn't name gets a gentler corner instead.
+    radius: { control, card: radiusLength(radius.card) ?? (parseFloat(control) * (control.endsWith("px") ? 1 : 16) > 24 ? "16px" : control) },
+    button: {
+      textTransform: button.textTransform === "uppercase" ? "uppercase" : "none",
+      fontWeight: /^[1-9]00$/.test(String(button.fontWeight ?? "")) ? String(button.fontWeight) : "600"
+    },
+    scheme,
+    source: raw.source === "declared" || raw.source === "mixed" ? raw.source : "measured"
+  };
+}
+function designTokensHash(tokens) {
+  const stable = (v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, stable(v[k])])) : v;
+  const text = JSON.stringify(stable(tokens));
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+function designTokenCssVars(tokens) {
+  return {
+    "--sk-site-bg": tokens.colors.background,
+    "--sk-site-surface": tokens.colors.surface,
+    "--sk-site-text": tokens.colors.text,
+    "--sk-site-muted": tokens.colors.muted,
+    "--sk-site-primary": tokens.colors.primary,
+    "--sk-site-on-primary": tokens.colors.onPrimary,
+    "--sk-site-border": tokens.colors.border,
+    "--sk-site-font-body": tokens.fonts.body,
+    "--sk-site-font-heading": tokens.fonts.heading,
+    "--sk-site-radius-control": tokens.radius.control,
+    "--sk-site-radius-card": tokens.radius.card,
+    "--sk-site-button-transform": tokens.button.textTransform,
+    "--sk-site-button-weight": tokens.button.fontWeight
+  };
+}
+var POPUP_BLOCK_TYPES = ["heading", "text", "image", "button", "divider"];
+var POPUP_BLOCK_LIMITS = {
+  blocks: 12,
+  heading: 120,
+  /** Sanitized HTML length for one text block. */
+  textHtml: 4e3,
+  /** Visible characters across one text block. */
+  textPlain: 1200,
+  buttonText: 40,
+  imageAlt: 200,
+  buttons: 2,
+  images: 3
+};
+function isSafePopupUrl(value, kind = "link") {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  if (!v || v.length > 2048) return false;
+  for (let i = 0; i < v.length; i++) {
+    const code = v.charCodeAt(i);
+    if (code <= 32 || code >= 127 && code <= 159) return false;
+  }
+  if (v.startsWith("/")) return !v.startsWith("//") && !v.startsWith("/\\");
+  if (v.startsWith("#")) return kind === "link" && v.length > 1;
+  let url;
+  try {
+    url = new URL(v);
+  } catch {
+    return false;
+  }
+  if (kind === "image") return url.protocol === "https:";
+  return ["https:", "http:", "mailto:", "tel:"].includes(url.protocol);
+}
+var ALLOWED_TAGS = /* @__PURE__ */ new Set(["p", "br", "strong", "b", "em", "i", "u", "s", "a", "ul", "ol", "li"]);
+var DROPPED_WITH_CONTENT = /* @__PURE__ */ new Set(["script", "style", "iframe", "object", "embed", "template", "noscript", "svg", "math", "textarea", "select", "title", "head"]);
+var VOID = /* @__PURE__ */ new Set(["br"]);
+var escapeAttr = (v) => v.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+function hrefOf(attrs) {
+  const m = attrs.match(/\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/i);
+  if (!m) return null;
+  const raw = (m[1] ?? m[2] ?? m[3] ?? "").replace(/&amp;/g, "&").trim();
+  return raw;
+}
+function sanitizePopupHtml(html) {
+  if (typeof html !== "string" || !html) return "";
+  const out = [];
+  const open = [];
+  let dropDepth = 0;
+  let dropTag = "";
+  const token = /<!--[\s\S]*?-->|<\/?([a-zA-Z][a-zA-Z0-9-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>|<|[^<]+/g;
+  let m;
+  while (m = token.exec(html)) {
+    const piece = m[0];
+    if (piece.startsWith("<!--")) continue;
+    const name = m[1]?.toLowerCase();
+    if (!name) {
+      if (dropDepth) continue;
+      out.push(piece === "<" ? "&lt;" : piece.replace(/>/g, "&gt;"));
+      continue;
+    }
+    const closing = piece.startsWith("</");
+    if (dropDepth) {
+      if (name === dropTag) dropDepth += closing ? -1 : piece.endsWith("/>") ? 0 : 1;
+      continue;
+    }
+    if (DROPPED_WITH_CONTENT.has(name)) {
+      if (!closing && !piece.endsWith("/>")) {
+        dropDepth = 1;
+        dropTag = name;
+      }
+      continue;
+    }
+    if (!ALLOWED_TAGS.has(name)) continue;
+    const tag = name === "b" ? "strong" : name === "i" ? "em" : name;
+    if (closing) {
+      const at = open.lastIndexOf(tag);
+      if (at === -1) continue;
+      while (open.length > at) out.push(`</${open.pop()}>`);
+      continue;
+    }
+    if (VOID.has(tag)) {
+      out.push("<br>");
+      continue;
+    }
+    if (tag === "a") {
+      const href = hrefOf(m[2] ?? "");
+      if (!href || !isSafePopupUrl(href, "link")) continue;
+      const external = /^https?:/i.test(href);
+      out.push(`<a href="${escapeAttr(href)}"${external ? ' target="_blank" rel="noopener noreferrer"' : ""}>`);
+      open.push("a");
+      continue;
+    }
+    out.push(`<${tag}>`);
+    open.push(tag);
+  }
+  while (open.length) out.push(`</${open.pop()}>`);
+  return out.join("").trim();
+}
+function popupHtmlText(html) {
+  return html.replace(/<br>/g, "\n").replace(/<\/(p|li)>/g, "\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+var str = (v) => typeof v === "string" ? v.trim() : "";
+function normalizePopupBlocks(input) {
+  const errors = [];
+  const blocks = [];
+  if (!Array.isArray(input)) return { blocks, errors: input == null ? [] : ["Blocks must be a list."] };
+  if (input.length > POPUP_BLOCK_LIMITS.blocks) errors.push(`A popup can have at most ${POPUP_BLOCK_LIMITS.blocks} blocks.`);
+  let buttons = 0;
+  let images = 0;
+  input.slice(0, POPUP_BLOCK_LIMITS.blocks).forEach((raw, i) => {
+    const where = `Block ${i + 1}`;
+    const b = raw && typeof raw === "object" ? raw : {};
+    switch (b.type) {
+      case "heading": {
+        const text = str(b.text);
+        if (!text) errors.push(`${where}: the heading is empty.`);
+        else if (text.length > POPUP_BLOCK_LIMITS.heading) errors.push(`${where}: the heading is over ${POPUP_BLOCK_LIMITS.heading} characters.`);
+        else blocks.push({ type: "heading", text });
+        return;
+      }
+      case "text": {
+        const html = sanitizePopupHtml(b.html);
+        const plain = popupHtmlText(html);
+        if (!plain) errors.push(`${where}: the text is empty.`);
+        else if (html.length > POPUP_BLOCK_LIMITS.textHtml || plain.length > POPUP_BLOCK_LIMITS.textPlain) {
+          errors.push(`${where}: the text is over ${POPUP_BLOCK_LIMITS.textPlain} characters.`);
+        } else blocks.push({ type: "text", html });
+        return;
+      }
+      case "image": {
+        const url = str(b.url);
+        const alt = str(b.alt);
+        if (!isSafePopupUrl(url, "image")) errors.push(`${where}: the image needs an https URL or a path on the site.`);
+        else if (!alt) errors.push(`${where}: describe the image for screen readers (alt text).`);
+        else if (alt.length > POPUP_BLOCK_LIMITS.imageAlt) errors.push(`${where}: the alt text is over ${POPUP_BLOCK_LIMITS.imageAlt} characters.`);
+        else if (++images > POPUP_BLOCK_LIMITS.images) errors.push(`A popup can have at most ${POPUP_BLOCK_LIMITS.images} images.`);
+        else blocks.push({ type: "image", url, alt });
+        return;
+      }
+      case "button": {
+        const text = str(b.text);
+        const url = str(b.url);
+        if (!text) errors.push(`${where}: the button needs text.`);
+        else if (text.length > POPUP_BLOCK_LIMITS.buttonText) errors.push(`${where}: the button text is over ${POPUP_BLOCK_LIMITS.buttonText} characters.`);
+        else if (!isSafePopupUrl(url, "link")) errors.push(`${where}: the button needs a link (a path on the site, https, mailto: or tel:).`);
+        else if (++buttons > POPUP_BLOCK_LIMITS.buttons) errors.push(`A popup can have at most ${POPUP_BLOCK_LIMITS.buttons} buttons.`);
+        else blocks.push({ type: "button", text, url, variant: b.variant === "secondary" ? "secondary" : "primary" });
+        return;
+      }
+      case "divider":
+        blocks.push({ type: "divider" });
+        return;
+      default:
+        errors.push(`${where}: unknown block type "${String(b.type ?? "")}".`);
+    }
+  });
+  if (!errors.length && !blocks.some((b) => b.type !== "divider")) errors.push("A popup needs at least one heading, text, image or button.");
+  return { blocks, errors };
+}
+function popupBlocksText(blocks) {
+  const heading = blocks.find((b) => b.type === "heading")?.text ?? "";
+  const body = blocks.filter((b) => b.type === "text").map((b) => popupHtmlText(b.html)).join("\n\n");
+  return { heading, body };
+}
+
+export { DESIGN_TOKENS_VERSION, POPUP_BLOCK_LIMITS, POPUP_BLOCK_TYPES, designTokenCssVars, designTokensHash, isSafePopupUrl, mixHex, normalizeDesignTokens, normalizePopupBlocks, popupBlocksText, popupHtmlText, readableOn, sanitizePopupHtml, toHexColor };

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@sonordev/contracts",
+  "version": "1.0.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 signing and portfolio metrics. Pure functions, no dependencies.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/upforge-dev/site-kit.git",
+    "directory": "packages/contracts"
+  },
+  "keywords": [
+    "sonor",
+    "site-kit",
+    "contracts"
+  ],
+  "sideEffects": false,
+  "exports": {
+    "./forms": {
+      "types": "./dist/forms.d.ts",
+      "import": "./dist/forms.mjs",
+      "require": "./dist/forms.js"
+    },
+    "./llms": {
+      "types": "./dist/llms.d.ts",
+      "import": "./dist/llms.mjs",
+      "require": "./dist/llms.js"
+    },
+    "./slots": {
+      "types": "./dist/slots.d.ts",
+      "import": "./dist/slots.mjs",
+      "require": "./dist/slots.js"
+    },
+    "./website": {
+      "types": "./dist/website.d.ts",
+      "import": "./dist/website.mjs",
+      "require": "./dist/website.js"
+    },
+    "./color": {
+      "types": "./dist/color.d.ts",
+      "import": "./dist/color.mjs",
+      "require": "./dist/color.js"
+    },
+    "./fleet": {
+      "types": "./dist/fleet.d.ts",
+      "import": "./dist/fleet.mjs",
+      "require": "./dist/fleet.js"
+    },
+    "./sites": {
+      "types": "./dist/sites.d.ts",
+      "import": "./dist/sites.mjs",
+      "require": "./dist/sites.js"
+    },
+    "./seo-pages": {
+      "types": "./dist/seo-pages.d.ts",
+      "import": "./dist/seo-pages.mjs",
+      "require": "./dist/seo-pages.js"
+    },
+    "./seo-meta": {
+      "types": "./dist/seo-meta.d.ts",
+      "import": "./dist/seo-meta.mjs",
+      "require": "./dist/seo-meta.js"
+    },
+    "./portfolio": {
+      "types": "./dist/portfolio.d.ts",
+      "import": "./dist/portfolio.mjs",
+      "require": "./dist/portfolio.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "dist/*.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "cd ../.. && pnpm build:contracts",
+    "test": "cd ../.. && pnpm test:contracts",
+    "prepublishOnly": "cd ../.. && pnpm test:contracts && pnpm build:contracts"
+  }
+}