@sonordev/contracts 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.7.0
+
+- Add `editorial-media`: shared section/takeaway text identities, article photo placement diagnostics, and source-image eligibility constants for APIs and site renderers.
+
+
 ## 2.6.0
 
 A minor release: one new entry, `@sonordev/contracts/knowledge`. Every other entry is unchanged.

package/README.md

@@ -434,3 +434,8 @@ Edit `src/contracts/<entry>.ts` in the site-kit repo, run
 `pnpm test:contracts`, and bump this package's version. A breaking change to
 a shape bumps the major and that contract's own `*_VERSION` constant.
 `pnpm build:contracts` builds it and checks every entry loads both ways.
+
+
+### Editorial media
+
+`@sonordev/contracts/editorial-media` exports `resolveArticlePhotoPlacements(html, photos)`, returning section targets and a status/offset for each explicit placement. Both the editor and article renderer use this contract; a heading with no eligible prose is reported as `no_paragraph`, and missing/ambiguous anchors never drift to another section. `editorialTextId` creates content identities for explicit takeaway assignments. Source-image format, size and completed-art exclusions are shared by the picker and resolver.

package/dist/editorial-media.d.ts

@@ -0,0 +1,39 @@
+/** Shared article placement and source eligibility rules. Pure, server/client safe. */
+export type EditorialPhotoPlacement = {
+    kind: 'after_intro';
+} | {
+    kind: 'after_heading';
+    heading: string;
+    headingId?: string;
+};
+export type ArticlePhotoPlacementStatus = 'placed' | 'missing_heading' | 'ambiguous_heading' | 'no_paragraph' | 'already_present' | 'unassigned';
+export interface EditorialHeadingTarget {
+    id: string;
+    text: string;
+    level: number;
+    eligible: boolean;
+}
+export declare function editorialPlainText(value: string): string;
+/** A text identity, never a positional index. Editing the meaning requires a new assignment. */
+export declare function editorialTextId(kind: 'section' | 'takeaway', text: string): string;
+export declare function resolveArticlePhotoPlacements(html: string, photos?: Array<{
+    placement?: EditorialPhotoPlacement;
+    url?: string;
+}>): {
+    headings: {
+        id: string;
+        text: string;
+        level: number;
+        eligible: boolean;
+    }[];
+    placements: {
+        index: number;
+        status: ArticlePhotoPlacementStatus;
+        offset?: number;
+    }[];
+};
+export declare const EDITORIAL_PHOTO_MIME_TYPES: readonly ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/avif'];
+export declare const EDITORIAL_PHOTO_MAX_BYTES: number;
+/** The same generated-art path exclusion is used by the picker and source resolver. */
+export declare const FINISHED_EDITORIAL_ART_PATHS: readonly ['Blog/Cards', 'Blog/Carousel', 'Broadcast/Cards', 'Broadcast/StylePreview', 'Reviews/Broadcast', 'Reviews/Photo', 'Reviews/StylePreview'];
+export declare function isFinishedEditorialArtwork(path: string): boolean;

package/dist/editorial-media.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// src/contracts/editorial-media.ts
+var voidElements = /* @__PURE__ */ new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+var rawElements = /* @__PURE__ */ new Set(["pre", "code", "script", "style", "textarea", "xmp", "template"]);
+var excludedAncestors = /* @__PURE__ */ new Set(["figure", "table", "ul", "ol", "blockquote", "aside", "nav", "header", "footer"]);
+var tags = () => /<!--[\s\S]*?(?:-->|$)|<\/?[a-z][\w:-]*(?=[\s/>])(?:[^"'<>]|"[^"]*"|'[^']*')*>/gi;
+function editorialPlainText(value) {
+  const entities = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", rsquo: "\u2019", lsquo: "\u2018", ldquo: "\u201C", rdquo: "\u201D", ndash: "\u2013", mdash: "\u2014" };
+  return value.replace(/<!--[\s\S]*?-->/g, "").replace(tags(), "").replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (full, entity) => {
+    if (!entity.startsWith("#")) return entities[entity.toLowerCase()] ?? full;
+    const number = entity[1].toLowerCase() === "x" ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10);
+    return number > 0 && number <= 1114111 ? String.fromCodePoint(number) : full;
+  }).replace(/\s+/g, " ").trim();
+}
+function editorialTextId(kind, text) {
+  const normalized = editorialPlainText(text);
+  let hash = 2166136261;
+  for (let i = 0; i < normalized.length; i++) hash = Math.imul(hash ^ normalized.charCodeAt(i), 16777619);
+  return `${kind}-${(hash >>> 0).toString(16).padStart(8, "0")}-${normalized.length}`;
+}
+function attributes(tag) {
+  const out = /* @__PURE__ */ new Map();
+  const body = tag.replace(/^<[^\s>]+/, "").replace(/\/?\s*>$/, "");
+  for (const match of body.matchAll(/([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) out.set(match[1].toLowerCase(), editorialPlainText(match[2] ?? match[3] ?? match[4] ?? ""));
+  return out;
+}
+function resolveArticlePhotoPlacements(html, photos = []) {
+  const pattern = tags();
+  const stack = [];
+  const headings = [];
+  const paragraphs = [];
+  const existing = /* @__PURE__ */ new Set(), existingSlots = /* @__PURE__ */ new Set();
+  let token;
+  while (token = pattern.exec(html)) {
+    const tag = token[0];
+    if (tag.startsWith("<!--")) continue;
+    const name = /^<\/?([\w:-]+)/.exec(tag)[1].toLowerCase();
+    if (tag.startsWith("</")) {
+      const at = stack.map((frame2) => frame2.name).lastIndexOf(name);
+      if (at < 0) continue;
+      const frame = stack[at];
+      if (frame.eligible) {
+        const text = editorialPlainText(html.slice(frame.inner, token.index));
+        if (/^h[1-6]$/.test(name)) headings.push({ id: frame.id || editorialTextId("section", text), text, level: Number(name[1]), start: frame.start, end: pattern.lastIndex, eligible: false });
+        if (name === "p" && text) paragraphs.push({ start: frame.start, end: pattern.lastIndex });
+      }
+      stack.length = at;
+      continue;
+    }
+    if (rawElements.has(name)) {
+      const closing = new RegExp(`</${name}\\s*>`, "gi");
+      closing.lastIndex = pattern.lastIndex;
+      if (!closing.exec(html)) break;
+      pattern.lastIndex = closing.lastIndex;
+      continue;
+    }
+    const attrs = attributes(tag);
+    if (name === "img" && attrs.has("src")) existing.add(attrs.get("src"));
+    if (name === "figure" && /^\d+$/.test(attrs.get("data-sk-editorial-photo") ?? "")) existingSlots.add(Number(attrs.get("data-sk-editorial-photo")));
+    if (voidElements.has(name) || /\/\s*>$/.test(tag)) continue;
+    stack.push({ name, start: token.index, inner: pattern.lastIndex, id: attrs.get("id"), eligible: !stack.some((frame) => excludedAncestors.has(frame.name)) });
+  }
+  const paragraphFor = (heading) => {
+    const next = headings.find((item) => item.start > heading.start);
+    return paragraphs.find((p) => p.start >= heading.end && (!next || p.end < next.start));
+  };
+  for (const heading of headings) heading.eligible = !!paragraphFor(heading);
+  const placements = photos.map((photo, index) => {
+    if (existingSlots.has(index) || photo.url && existing.has(photo.url)) return { index, status: "already_present" };
+    let paragraph;
+    if (photo.placement?.kind === "after_intro") {
+      const firstSection = headings.find((h) => h.level > 1);
+      paragraph = paragraphs.find((p) => !firstSection || p.start < firstSection.start);
+    } else if (photo.placement?.kind === "after_heading") {
+      const placement = photo.placement;
+      const matches = headings.filter((h) => placement.headingId ? h.id === placement.headingId : h.text === editorialPlainText(placement.heading));
+      if (matches.length !== 1) return { index, status: matches.length ? "ambiguous_heading" : "missing_heading" };
+      paragraph = paragraphFor(matches[0]);
+    } else return { index, status: "unassigned" };
+    if (!paragraph) return { index, status: "no_paragraph" };
+    if (photo.url) existing.add(photo.url);
+    return { index, status: "placed", offset: paragraph.end };
+  });
+  return { headings: headings.map(({ start: _start, end: _end, ...heading }) => heading), placements };
+}
+var EDITORIAL_PHOTO_MIME_TYPES = ["image/jpeg", "image/jpg", "image/png", "image/webp", "image/avif"];
+var EDITORIAL_PHOTO_MAX_BYTES = 10 * 1024 * 1024;
+var FINISHED_EDITORIAL_ART_PATHS = ["Blog/Cards", "Blog/Carousel", "Broadcast/Cards", "Broadcast/StylePreview", "Reviews/Broadcast", "Reviews/Photo", "Reviews/StylePreview"];
+function isFinishedEditorialArtwork(path) {
+  const normalized = `/${path}`.toLowerCase();
+  return FINISHED_EDITORIAL_ART_PATHS.some((part) => normalized.includes(`/${part.toLowerCase()}/`));
+}
+
+exports.EDITORIAL_PHOTO_MAX_BYTES = EDITORIAL_PHOTO_MAX_BYTES;
+exports.EDITORIAL_PHOTO_MIME_TYPES = EDITORIAL_PHOTO_MIME_TYPES;
+exports.FINISHED_EDITORIAL_ART_PATHS = FINISHED_EDITORIAL_ART_PATHS;
+exports.editorialPlainText = editorialPlainText;
+exports.editorialTextId = editorialTextId;
+exports.isFinishedEditorialArtwork = isFinishedEditorialArtwork;
+exports.resolveArticlePhotoPlacements = resolveArticlePhotoPlacements;

package/dist/editorial-media.mjs

@@ -0,0 +1,93 @@
+// src/contracts/editorial-media.ts
+var voidElements = /* @__PURE__ */ new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+var rawElements = /* @__PURE__ */ new Set(["pre", "code", "script", "style", "textarea", "xmp", "template"]);
+var excludedAncestors = /* @__PURE__ */ new Set(["figure", "table", "ul", "ol", "blockquote", "aside", "nav", "header", "footer"]);
+var tags = () => /<!--[\s\S]*?(?:-->|$)|<\/?[a-z][\w:-]*(?=[\s/>])(?:[^"'<>]|"[^"]*"|'[^']*')*>/gi;
+function editorialPlainText(value) {
+  const entities = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", rsquo: "\u2019", lsquo: "\u2018", ldquo: "\u201C", rdquo: "\u201D", ndash: "\u2013", mdash: "\u2014" };
+  return value.replace(/<!--[\s\S]*?-->/g, "").replace(tags(), "").replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (full, entity) => {
+    if (!entity.startsWith("#")) return entities[entity.toLowerCase()] ?? full;
+    const number = entity[1].toLowerCase() === "x" ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10);
+    return number > 0 && number <= 1114111 ? String.fromCodePoint(number) : full;
+  }).replace(/\s+/g, " ").trim();
+}
+function editorialTextId(kind, text) {
+  const normalized = editorialPlainText(text);
+  let hash = 2166136261;
+  for (let i = 0; i < normalized.length; i++) hash = Math.imul(hash ^ normalized.charCodeAt(i), 16777619);
+  return `${kind}-${(hash >>> 0).toString(16).padStart(8, "0")}-${normalized.length}`;
+}
+function attributes(tag) {
+  const out = /* @__PURE__ */ new Map();
+  const body = tag.replace(/^<[^\s>]+/, "").replace(/\/?\s*>$/, "");
+  for (const match of body.matchAll(/([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) out.set(match[1].toLowerCase(), editorialPlainText(match[2] ?? match[3] ?? match[4] ?? ""));
+  return out;
+}
+function resolveArticlePhotoPlacements(html, photos = []) {
+  const pattern = tags();
+  const stack = [];
+  const headings = [];
+  const paragraphs = [];
+  const existing = /* @__PURE__ */ new Set(), existingSlots = /* @__PURE__ */ new Set();
+  let token;
+  while (token = pattern.exec(html)) {
+    const tag = token[0];
+    if (tag.startsWith("<!--")) continue;
+    const name = /^<\/?([\w:-]+)/.exec(tag)[1].toLowerCase();
+    if (tag.startsWith("</")) {
+      const at = stack.map((frame2) => frame2.name).lastIndexOf(name);
+      if (at < 0) continue;
+      const frame = stack[at];
+      if (frame.eligible) {
+        const text = editorialPlainText(html.slice(frame.inner, token.index));
+        if (/^h[1-6]$/.test(name)) headings.push({ id: frame.id || editorialTextId("section", text), text, level: Number(name[1]), start: frame.start, end: pattern.lastIndex, eligible: false });
+        if (name === "p" && text) paragraphs.push({ start: frame.start, end: pattern.lastIndex });
+      }
+      stack.length = at;
+      continue;
+    }
+    if (rawElements.has(name)) {
+      const closing = new RegExp(`</${name}\\s*>`, "gi");
+      closing.lastIndex = pattern.lastIndex;
+      if (!closing.exec(html)) break;
+      pattern.lastIndex = closing.lastIndex;
+      continue;
+    }
+    const attrs = attributes(tag);
+    if (name === "img" && attrs.has("src")) existing.add(attrs.get("src"));
+    if (name === "figure" && /^\d+$/.test(attrs.get("data-sk-editorial-photo") ?? "")) existingSlots.add(Number(attrs.get("data-sk-editorial-photo")));
+    if (voidElements.has(name) || /\/\s*>$/.test(tag)) continue;
+    stack.push({ name, start: token.index, inner: pattern.lastIndex, id: attrs.get("id"), eligible: !stack.some((frame) => excludedAncestors.has(frame.name)) });
+  }
+  const paragraphFor = (heading) => {
+    const next = headings.find((item) => item.start > heading.start);
+    return paragraphs.find((p) => p.start >= heading.end && (!next || p.end < next.start));
+  };
+  for (const heading of headings) heading.eligible = !!paragraphFor(heading);
+  const placements = photos.map((photo, index) => {
+    if (existingSlots.has(index) || photo.url && existing.has(photo.url)) return { index, status: "already_present" };
+    let paragraph;
+    if (photo.placement?.kind === "after_intro") {
+      const firstSection = headings.find((h) => h.level > 1);
+      paragraph = paragraphs.find((p) => !firstSection || p.start < firstSection.start);
+    } else if (photo.placement?.kind === "after_heading") {
+      const placement = photo.placement;
+      const matches = headings.filter((h) => placement.headingId ? h.id === placement.headingId : h.text === editorialPlainText(placement.heading));
+      if (matches.length !== 1) return { index, status: matches.length ? "ambiguous_heading" : "missing_heading" };
+      paragraph = paragraphFor(matches[0]);
+    } else return { index, status: "unassigned" };
+    if (!paragraph) return { index, status: "no_paragraph" };
+    if (photo.url) existing.add(photo.url);
+    return { index, status: "placed", offset: paragraph.end };
+  });
+  return { headings: headings.map(({ start: _start, end: _end, ...heading }) => heading), placements };
+}
+var EDITORIAL_PHOTO_MIME_TYPES = ["image/jpeg", "image/jpg", "image/png", "image/webp", "image/avif"];
+var EDITORIAL_PHOTO_MAX_BYTES = 10 * 1024 * 1024;
+var FINISHED_EDITORIAL_ART_PATHS = ["Blog/Cards", "Blog/Carousel", "Broadcast/Cards", "Broadcast/StylePreview", "Reviews/Broadcast", "Reviews/Photo", "Reviews/StylePreview"];
+function isFinishedEditorialArtwork(path) {
+  const normalized = `/${path}`.toLowerCase();
+  return FINISHED_EDITORIAL_ART_PATHS.some((part) => normalized.includes(`/${part.toLowerCase()}/`));
+}
+
+export { EDITORIAL_PHOTO_MAX_BYTES, EDITORIAL_PHOTO_MIME_TYPES, FINISHED_EDITORIAL_ART_PATHS, editorialPlainText, editorialTextId, isFinishedEditorialArtwork, resolveArticlePhotoPlacements };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.6.0",
+  "version": "2.7.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, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, and which Sonor records Signal reads into a project's knowledge and the address each one is stored under. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
@@ -110,7 +110,12 @@
       "import": "./dist/knowledge.mjs",
       "require": "./dist/knowledge.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./editorial-media": {
+      "types": "./dist/editorial-media.d.ts",
+      "import": "./dist/editorial-media.mjs",
+      "require": "./dist/editorial-media.js"
+    }
   },
   "typesVersions": {
     "*": {