@sonordev/contracts 2.5.0 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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.
+
+- **New entry `@sonordev/contracts/knowledge`**: which Sonor records Signal reads into a project's knowledge, where each one's knowledge is stored, and how big a page sync may be, so the API that announces a change and Signal, which indexes it, agree.
+  - `KNOWLEDGE_RECORD_KINDS` lists the record kinds (`portfolio`, `proof`, `faq`, `review`, `article`, `offering`), and `isKnowledgeRecordKind(value)` checks one.
+  - `knowledgeRecordSourceUrl(kind, id, anchor?)` builds a record's address (`faq://<id>`, `article://<id>#pricing`) and `knowledgeRecordPrefix(kind)` the `<kind>://` all of a kind's addresses start with.
+  - `knowledgeRecordKindOf(url)` tells a record's row from a page passage by its scheme, and `knowledgeRecordRefOf(url)` returns the `{ kind, id }` an address names, the legacy `commerce://offering/<id>` (`legacyOfferingSourceUrl`) included.
+  - `KNOWLEDGE_SYNC_MAX_PAGES` (500), `KNOWLEDGE_SYNC_PATH_MAX_LENGTH` (2048) and `KNOWLEDGE_SYNC_SITE_MAX_LENGTH` (253) are the limits of one page sync, and `KnowledgePageChange` is the shape of each page in it. Signal applies every removal in a call and reads the changed pages in the order given, so a sender puts removals first.
+
 ## 2.5.0
 
 A minor release: one new entry, `@sonordev/contracts/sentences`, and a cache tag for commerce. Every other entry is unchanged.

package/README.md

@@ -27,6 +27,7 @@ pnpm add @sonordev/contracts
 | `@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 |
 | `@sonordev/contracts/sentences` | Where prose splits into sentences, without dropping a word or ending one at "p.m." (`splitSentences`) | anything that cuts an excerpt, a social slide or a summary out of an article: the Sonor API's carousels, Signal's article pipeline |
+| `@sonordev/contracts/knowledge` | Which Sonor records Signal reads into a project's knowledge, the address each one's knowledge is stored under (`portfolio://<id>`), and the limits of the call that tells Signal a site's pages changed | the Sonor API sends those calls and Signal answers them |
 
 ## Schema placeholders
 
@@ -350,6 +351,69 @@ short forms (a period after one it doesn't know ends a sentence, so "Sra.
 García" splits after "Sra."), and the next sentence has to start with `A` to
 `Z` or a digit.
 
+## The knowledge contract
+
+Signal answers questions about a business from what it has read: the
+passages of the site's live pages, and the business's own records in Sonor.
+The Sonor API tells Signal when either changes, and Signal indexes it. Both
+have to agree on which records count, how a stored row says which record it
+came from, and how big a page sync may be. If they don't, a record the API
+announces is refused, or a row Signal wrote reads as a page. Anything that
+shows what Signal has read, like the dashboard's view of it, reads stored
+addresses by the same rules.
+
+- **Record kinds.** `KNOWLEDGE_RECORD_KINDS` is `portfolio` (case studies),
+  `proof` (proof records), `faq` (managed FAQs), `review`, `article` and
+  `offering` (commerce offerings), in the order the dashboard lists them.
+  `isKnowledgeRecordKind(value)` is true only for one of them, spelled exactly.
+- **Addresses.** A record's knowledge is stored under `<kind>://<id>`, and
+  any further chunk under `<kind>://<id>#<anchor>` (an article indexed in full
+  is split by heading). `knowledgeRecordSourceUrl(kind, id, anchor?)` builds
+  one and `knowledgeRecordPrefix(kind)` gives the `<kind>://` every address of
+  that kind starts with. The id is the record's UUID, and the caller checks
+  it: one holding `#`, `?`, `/` or whitespace can't be read back. A page's
+  passages are stored under the page's https URL instead, so the scheme alone
+  tells a record's rows apart. The content type can't: an article's record
+  has the same type as the page passages beside it, because a live article is
+  a page on the site.
+- **Reading an address.** `knowledgeRecordKindOf(url)` is the kind by scheme
+  alone, or `null` for a page passage, an older page summary or a note. It's
+  the test for whether a row belongs to a record. `knowledgeRecordRefOf(url)`
+  is `{ kind, id }` for the record an address names, or `null` when it names
+  none; the id runs to the first `#`, `?`, `/` or whitespace. Both ignore the
+  scheme's case and surrounding whitespace.
+- **The legacy offering address.** Offerings were once stored under
+  `commerce://offering/<id>` (`legacyOfferingSourceUrl(id)`). Nothing writes
+  it now, and Signal switches each such row off the next time its offering
+  syncs. Until then `knowledgeRecordRefOf` names the offering, while
+  `knowledgeRecordKindOf` doesn't count the row as a record's.
+- **A page sync.** One call names at most `KNOWLEDGE_SYNC_MAX_PAGES` (500)
+  pages, each a `KnowledgePageChange` (`{ site?, path, removed? }`) with a
+  path of at most `KNOWLEDGE_SYNC_PATH_MAX_LENGTH` (2048) characters and a
+  host of at most `KNOWLEDGE_SYNC_SITE_MAX_LENGTH` (253). Signal refuses a
+  longer list, path or host outright, so a sender keeps within them before it
+  calls. Signal applies every removal in the call, then reads the changed
+  pages in the order given, as many as it reads in one call; the rest wait for
+  its nightly sweep. So put removals first, then the pages that matter most,
+  and cut the list after ordering it.
+
+```ts
+import {
+  KNOWLEDGE_SYNC_MAX_PAGES,
+  knowledgeRecordRefOf,
+  knowledgeRecordSourceUrl,
+} from '@sonordev/contracts/knowledge'
+
+knowledgeRecordSourceUrl('faq', id)
+// 'faq://<id>'
+
+knowledgeRecordRefOf('article://<id>#part-2')
+// { kind: 'article', id: '<id>' }
+
+const batch = [...removed, ...changed].slice(0, KNOWLEDGE_SYNC_MAX_PAGES)
+// removals first, so the cut drops changed pages before any removal
+```
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.
@@ -370,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/dist/knowledge.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Knowledge contract: which Sonor records Signal reads into a project's
+ * knowledge, the address each record's knowledge is stored under, and the
+ * limits of the call that tells Signal a site's pages changed. The Sonor API
+ * makes those calls and Signal answers them, so both import this as
+ * `@sonordev/contracts/knowledge` instead of keeping lists that drift apart.
+ * The dashboard, which shows the owner what Signal read, reads stored
+ * addresses by the same rules.
+ *
+ * A record's knowledge is stored under a URI built from its kind and id:
+ * `<kind>://<id>` for its first chunk and `<kind>://<id>#<anchor>` for any
+ * more (an article indexed in full, split by heading). The scheme is what
+ * tells a record's rows apart from a page's passages, which are stored under
+ * the page's https URL. The content type can't: an article's record has the
+ * same content type as the page passages beside it, because a live article is
+ * a page on the site.
+ */
+/**
+ * The kinds of Sonor record Signal indexes, in the order the dashboard lists
+ * them: case studies, proof records, managed FAQs, reviews, articles and
+ * commerce offerings. Each kind is also its URI scheme.
+ */
+export declare const KNOWLEDGE_RECORD_KINDS: readonly ["portfolio", "proof", "faq", "review", "article", "offering"];
+export type KnowledgeRecordKind = (typeof KNOWLEDGE_RECORD_KINDS)[number];
+/** True for one of KNOWLEDGE_RECORD_KINDS, spelled exactly (lowercase). */
+export declare function isKnowledgeRecordKind(value: unknown): value is KnowledgeRecordKind;
+/** `<kind>://`, the start every address of that kind shares, for prefix queries. */
+export declare function knowledgeRecordPrefix(kind: KnowledgeRecordKind): string;
+/**
+ * Where a record's knowledge is stored: `<kind>://<id>` for its first chunk,
+ * `<kind>://<id>#<anchor>` for a further one. `id` is the record's UUID, and
+ * checking it is the caller's job: an empty id, or one holding `#`, `?`, `/`
+ * or whitespace, builds an address knowledgeRecordRefOf can't read back.
+ */
+export declare function knowledgeRecordSourceUrl(kind: KnowledgeRecordKind, id: string, anchor?: string | null): string;
+/**
+ * The address an offering had before offerings were records of their own:
+ * `commerce://offering/<id>`. Nothing writes it any more. Signal switches the
+ * row off the next time that offering syncs, and a reader counts it as the
+ * offering until then (knowledgeRecordRefOf).
+ */
+export declare function legacyOfferingSourceUrl(id: string): string;
+/**
+ * The kind of record a stored address belongs to, by its scheme
+ * (`article://<id>#part-2` is 'article'), or null for anything else: a page
+ * passage, an older page summary, a note. Case doesn't matter and surrounding
+ * whitespace is ignored. This is the test for "is this row a record's": it
+ * reads only the scheme, so it doesn't need an id, and an offering's legacy
+ * address isn't a record row by it.
+ */
+export declare function knowledgeRecordKindOf(sourceUrl: string | null | undefined): KnowledgeRecordKind | null;
+/** The record a stored address names. */
+export interface KnowledgeRecordRef {
+    kind: KnowledgeRecordKind;
+    id: string;
+}
+/**
+ * The record a stored address names (`portfolio://<id>#part-2` is
+ * `{ kind: 'portfolio', id }`), or null when it names none. An offering's
+ * legacy address (`commerce://offering/<id>`) names that offering. Case
+ * doesn't matter in the scheme, surrounding whitespace is ignored, and the id
+ * keeps its own case.
+ */
+export declare function knowledgeRecordRefOf(sourceUrl: string | null | undefined): KnowledgeRecordRef | null;
+/**
+ * One page of a site in a page sync: it changed (Signal reads it live) or
+ * left the site (`removed`: Signal switches its passages off). Signal applies
+ * every removal in a call, then reads the changed pages in the order given,
+ * as many as it reads in one call; the rest wait for its nightly sweep. So a
+ * sender puts removals first, then the pages that matter most.
+ */
+export interface KnowledgePageChange {
+    /** The host as the project's pages store it; null or absent is the project's primary domain. */
+    site?: string | null;
+    /** The page's path, from "/". */
+    path: string;
+    removed?: boolean;
+}
+/** The most pages one page sync may name. Signal refuses a longer list outright, so cut the list after ordering it. */
+export declare const KNOWLEDGE_SYNC_MAX_PAGES = 500;
+/** The longest path a page sync may name, in characters. */
+export declare const KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+/** The longest host a page sync may name, in characters (a DNS name's limit). */
+export declare const KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;

package/dist/knowledge.js

@@ -0,0 +1,48 @@
+'use strict';
+
+// src/contracts/knowledge.ts
+var KNOWLEDGE_RECORD_KINDS = Object.freeze(["portfolio", "proof", "faq", "review", "article", "offering"]);
+function isKnowledgeRecordKind(value) {
+  return typeof value === "string" && KNOWLEDGE_RECORD_KINDS.includes(value);
+}
+function knowledgeRecordPrefix(kind) {
+  return `${kind}://`;
+}
+function knowledgeRecordSourceUrl(kind, id, anchor) {
+  const base = `${knowledgeRecordPrefix(kind)}${id}`;
+  return anchor ? `${base}#${anchor}` : base;
+}
+function legacyOfferingSourceUrl(id) {
+  return `${LEGACY_OFFERING_PREFIX}${id}`;
+}
+var LEGACY_OFFERING_PREFIX = "commerce://offering/";
+var RECORD_SCHEME = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://`, "i");
+var RECORD_REF = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://([^#?/\\s]+)`, "i");
+var LEGACY_OFFERING_REF = /^commerce:\/\/offering\/([^#?/\s]+)/i;
+function knowledgeRecordKindOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const match = RECORD_SCHEME.exec(sourceUrl.trim());
+  return match ? match[1].toLowerCase() : null;
+}
+function knowledgeRecordRefOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const value = sourceUrl.trim();
+  const record = RECORD_REF.exec(value);
+  if (record) return { kind: record[1].toLowerCase(), id: record[2] };
+  const legacy = LEGACY_OFFERING_REF.exec(value);
+  return legacy ? { kind: "offering", id: legacy[1] } : null;
+}
+var KNOWLEDGE_SYNC_MAX_PAGES = 500;
+var KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+var KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;
+
+exports.KNOWLEDGE_RECORD_KINDS = KNOWLEDGE_RECORD_KINDS;
+exports.KNOWLEDGE_SYNC_MAX_PAGES = KNOWLEDGE_SYNC_MAX_PAGES;
+exports.KNOWLEDGE_SYNC_PATH_MAX_LENGTH = KNOWLEDGE_SYNC_PATH_MAX_LENGTH;
+exports.KNOWLEDGE_SYNC_SITE_MAX_LENGTH = KNOWLEDGE_SYNC_SITE_MAX_LENGTH;
+exports.isKnowledgeRecordKind = isKnowledgeRecordKind;
+exports.knowledgeRecordKindOf = knowledgeRecordKindOf;
+exports.knowledgeRecordPrefix = knowledgeRecordPrefix;
+exports.knowledgeRecordRefOf = knowledgeRecordRefOf;
+exports.knowledgeRecordSourceUrl = knowledgeRecordSourceUrl;
+exports.legacyOfferingSourceUrl = legacyOfferingSourceUrl;

package/dist/knowledge.mjs

@@ -0,0 +1,37 @@
+// src/contracts/knowledge.ts
+var KNOWLEDGE_RECORD_KINDS = Object.freeze(["portfolio", "proof", "faq", "review", "article", "offering"]);
+function isKnowledgeRecordKind(value) {
+  return typeof value === "string" && KNOWLEDGE_RECORD_KINDS.includes(value);
+}
+function knowledgeRecordPrefix(kind) {
+  return `${kind}://`;
+}
+function knowledgeRecordSourceUrl(kind, id, anchor) {
+  const base = `${knowledgeRecordPrefix(kind)}${id}`;
+  return anchor ? `${base}#${anchor}` : base;
+}
+function legacyOfferingSourceUrl(id) {
+  return `${LEGACY_OFFERING_PREFIX}${id}`;
+}
+var LEGACY_OFFERING_PREFIX = "commerce://offering/";
+var RECORD_SCHEME = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://`, "i");
+var RECORD_REF = new RegExp(`^(${KNOWLEDGE_RECORD_KINDS.join("|")})://([^#?/\\s]+)`, "i");
+var LEGACY_OFFERING_REF = /^commerce:\/\/offering\/([^#?/\s]+)/i;
+function knowledgeRecordKindOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const match = RECORD_SCHEME.exec(sourceUrl.trim());
+  return match ? match[1].toLowerCase() : null;
+}
+function knowledgeRecordRefOf(sourceUrl) {
+  if (typeof sourceUrl !== "string") return null;
+  const value = sourceUrl.trim();
+  const record = RECORD_REF.exec(value);
+  if (record) return { kind: record[1].toLowerCase(), id: record[2] };
+  const legacy = LEGACY_OFFERING_REF.exec(value);
+  return legacy ? { kind: "offering", id: legacy[1] } : null;
+}
+var KNOWLEDGE_SYNC_MAX_PAGES = 500;
+var KNOWLEDGE_SYNC_PATH_MAX_LENGTH = 2048;
+var KNOWLEDGE_SYNC_SITE_MAX_LENGTH = 253;
+
+export { KNOWLEDGE_RECORD_KINDS, KNOWLEDGE_SYNC_MAX_PAGES, KNOWLEDGE_SYNC_PATH_MAX_LENGTH, KNOWLEDGE_SYNC_SITE_MAX_LENGTH, isKnowledgeRecordKind, knowledgeRecordKindOf, knowledgeRecordPrefix, knowledgeRecordRefOf, knowledgeRecordSourceUrl, legacyOfferingSourceUrl };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.5.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, and where prose splits into sentences. Pure functions, no dependencies.",
+  "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": {
     "type": "git",
@@ -105,7 +105,17 @@
       "import": "./dist/sentences.mjs",
       "require": "./dist/sentences.js"
     },
-    "./package.json": "./package.json"
+    "./knowledge": {
+      "types": "./dist/knowledge.d.ts",
+      "import": "./dist/knowledge.mjs",
+      "require": "./dist/knowledge.js"
+    },
+    "./package.json": "./package.json",
+    "./editorial-media": {
+      "types": "./dist/editorial-media.d.ts",
+      "import": "./dist/editorial-media.mjs",
+      "require": "./dist/editorial-media.js"
+    }
   },
   "typesVersions": {
     "*": {