@sonordev/contracts 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2.12.0
+
+A minor release: `@sonordev/contracts/portfolio` now holds the structure of a case study's story. Every other entry is unchanged, and nothing already exported from `portfolio` changed.
+
+- **The case study arc.** `CASE_STUDY_STAGES` names the four beats every case study reads in (`problem`, `build`, `proof`, `outcome`), `CASE_STUDY_STAGE_COPY` gives each a generic name and the question it answers, `PORTFOLIO_SECTION_TYPES` is every section type in canonical reading order, and `SECTION_STAGE` / `sectionStage` say which stage each belongs to. The section list used to be kept separately by the Sonor API and agency-site-kit; this is now the one copy.
+- **Reading order.** `orderSections` always keeps the arc (hero, problem, build, proof, outcome, CTA) and keeps an agency's stored order only within a stage, so a reordered case study can no longer put its results above its challenges. `groupSectionsByStage` returns the beats a case study actually has, numbered in order. `PORTFOLIO_SECTION_ORDER` is derived from the list. Performance now reads before Results: the proof comes before the outcome.
+- **Stage status.** `caseStudyStageStatus` reports all four stages, complete only with the stage's core section (`STAGE_CORE_SECTION`), with one sentence on what's missing.
+- **Stage names.** An agency can call the four stages what it likes ("Heat", "Shape", "Temper", "Finish"); `CaseStudyStageNames` is that map, `stageName(names, stage)` reads it with the generic name as the fallback, `stageNamesProblems` validates it and `STAGE_NAME_MAX_CHARS` is the length limit. The ids never change; only what people see does.
+- **The narrative.** `CaseStudyNarrative` is a case study's thesis and one lede per stage, written for the project rather than borrowed from the house. `narrativeProblems` validates one, `NARRATIVE_MAX_CHARS` is the length limit and `CASE_STUDY_NARRATIVE_JSON_SCHEMA` the same rule as a schema. An absent narrative passes.
+- **The thread.** A challenge carries an `id` (`challengeId(n)`), a phase `resolves` challenges and a result `proves` them; `caseStudyFlowProblems` names every challenge nothing resolves or proves and every dangling reference, and passes content written before the thread existed.
+
+## 2.11.0
+
+- Add `@sonordev/contracts/public-url-host`: the pure `isBlockedPublicUrlHost` predicate shared by Sonor and Signal, including private IPv4 and IPv6 ranges, mapped/compatible IPv4, and local hostname suffixes. It uses the standard URL parser without Node dependencies. Scoped IPv6 addresses are refused without throwing. Callers retain URL validation, DNS resolution/address pinning, and redirect protections.
+
 ## 2.10.0
 
 A minor release: two new functions in `@sonordev/contracts/page-titles`. Every entry is otherwise unchanged.

package/README.md

@@ -25,7 +25,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/slot-content` | What a slot of each kind may hold (`normalizeSlotValue`), safe links, the rich-text parser. No `crypto`, so browsers can import it | the Sonor API, site-kit, the dashboard editor |
 | `@sonordev/contracts/site-cache` | The cache tags a site's Sonor fetches carry and the revalidation route's path, payload and ping | site-kit tags and serves the route, the Sonor API calls it |
 | `@sonordev/contracts/site-edit` | Edit on page: the messages between a framed site and the dashboard, trusted origins, how a slot is found on the page | site-kit's overlay, the dashboard's visual editor |
-| `@sonordev/contracts/portfolio` | Where a portfolio number comes from and which may headline; the live-frame message | the Sonor API, Signal, agency-site-kit |
+| `@sonordev/contracts/portfolio` | The case study arc: every section type, the stage each belongs to, the reading order, the narrative that opens each stage and the thread from a challenge to the phase that cleared it and the result that proves it. Also where a portfolio number comes from and which may headline, and the live-frame message | the Sonor API, Signal's case-study writer, the dashboard's editor, agency-site-kit |
 | `@sonordev/contracts/proposal-sitemap` | How a proposal's site plan counts its pages, when its before-and-after comparison may show, and whether the page counts stated elsewhere in the proposal add up | the Sonor API, Signal's proposal writer, the dashboard's proposal pages |
 | `@sonordev/contracts/voice` | The house voice's contraction rule. `findUncontracted` and `contractText` find and apply full forms that should be contractions; `findContracted` finds the contractions a question-form heading should expand | anything that checks or rewrites copy: Sonor's APIs and dashboard |
 | `@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 |
@@ -37,6 +37,22 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/page-titles` | A page's own name: its title without the brand (`titleHead`), a readable label from a slug (`slugLabel`), whether a value is a route placeholder like `:slug` (`isRoutePlaceholder`), whether a value is a page's address and not its name (`isPageAddress`), and whether a stored title is a name when every piece between its pipes is judged (`isPageName`) | Signal's site-architecture writer, the agency site kit's portfolio components |
 | `@sonordev/contracts/broadcast-layouts` | Which Broadcast card layouts are drawn (centered `headline`, low `anchor`), which retired IDs still read and what each draws as (`normalizeArticleCoverLayout`), the Broadcast styles, and the review compositions with the frozen draw that gives each review its own (`reviewCardVariationFromDigest`) | the Sonor API's card renderers and settings, Signal's agent tools, the dashboard's pickers |
 | `@sonordev/contracts/publication-branding` | What a publication's branding may hold and what a change may set (`createPublicationBrandingValidator`), how a change merges, the editorial charter, and safe font stacks | the Sonor API stores and resolves it, Signal checks an agent's change before filing it, the dashboard edits it |
+| `@sonordev/contracts/public-url-host` | Which literal hosts are refused as public fetch destinations (`isBlockedPublicUrlHost`) | the Sonor API and Signal's URL validators and network fetchers |
+
+## Public URL hosts
+
+`isBlockedPublicUrlHost(host)` shares the APIs' loopback, private IPv4,
+link-local, carrier-grade NAT, multicast/reserved IPv4, private IPv6 and local
+hostname checks. It checks IPv4-mapped and IPv4-compatible IPv6 destinations
+too, with or without brackets. It uses the standard `URL` parser, with no
+Node, DNS or network dependencies. Scoped IPv6 addresses are refused.
+
+Pass the **parsed `URL.hostname`**, so alternate IPv4 spellings such as
+`127.1` and `0x7f000001` are normalized first, or pass a DNS result's address.
+This predicate doesn't validate a URL or trim a raw string. A `false` result
+isn't proof a destination is public: the fetcher still validates the protocol,
+credentials and port, checks the DNS addresses it connects to, and applies its
+redirect policy on each hop. Those network protections stay in the APIs.
 
 ## Schema placeholders
 
@@ -740,9 +756,10 @@ valid, so the validator lives here once.
 
 ```ts
 import { createPublicationBrandingValidator } from '@sonordev/contracts/publication-branding'
+import { isBlockedPublicUrlHost } from '@sonordev/contracts/public-url-host'
 
-// Bind it once, to the server's own private-address guard.
-const branding = createPublicationBrandingValidator({ isBlockedHost })
+// Bind it once to the same literal-host policy both APIs use.
+const branding = createPublicationBrandingValidator({ isBlockedHost: isBlockedPublicUrlHost })
 
 branding.validatePublicationBrandingPatch({ colors: { primary: '#ABC' } })
 // { colors: { primary: '#aabbcc' } }
@@ -755,8 +772,10 @@ branding.mergePublicationBrandingPatch(saved, { identity: { logos: { dark: null
 - **`createPublicationBrandingValidator({ isBlockedHost })`** returns the
   validator. A URL leaf must be a public HTTPS URL without credentials;
   whether its host is private (loopback, a LAN range, link-local,
-  `localhost`) is the caller's guard, because that check needs Node. It gets
-  `new URL(value).hostname`, so IPv6 keeps its brackets.
+  `localhost`) uses the injected guard. Both APIs pass the shared
+  `public-url-host` predicate, which doesn't need Node. It gets
+  `new URL(value).hostname`, so IPv6 keeps its brackets. DNS and connection
+  checks remain the responsibility of the fetcher.
 - **`validatePublicationBranding`** reads a whole saved profile.
   **`validatePublicationBrandingPatch`** reads a change: a leaf set to `null`
   clears that override, and a card layout must be one that's drawn today.
@@ -782,6 +801,53 @@ The stored shape's version is `PUBLICATION_BRANDING_VERSION`. Resolving a
 profile against a project's own colors and its measured site design stays in
 the Sonor API.
 
+## The portfolio contract: the case study arc
+
+Every case study tells the same four-beat story, whatever an agency calls
+the beats: what was wrong, what we built, how we proved it holds up, and
+what it's doing for the client now. `@sonordev/contracts/portfolio` is
+where that story's structure lives, once, for the generator that writes it,
+the dashboard that edits it and every site that renders it.
+
+- **`CASE_STUDY_STAGES`** is the four beats in order: `problem`, `build`,
+  `proof`, `outcome`. The ids are deliberately plain; an agency's renderer
+  maps them to its own words. `CASE_STUDY_STAGE_COPY` gives each a generic
+  name and the question its sections answer.
+- **`PORTFOLIO_SECTION_TYPES`** is every section a case study can hold, in
+  canonical reading order: the hero, then each stage's sections, then the
+  SEO metadata and the closing CTA. `SECTION_STAGE` says which stage each
+  type belongs to (null for the hero, SEO and CTA, which sit outside the
+  story) and `sectionStage(type)` reads it for a string. Both are typed over
+  every section type, so a new type without a stage is a compile error.
+- **`orderSections(sections, { sectionsOrdered })`** is the reading order.
+  The arc always wins: hero, problem, build, proof, outcome, CTA. Within a
+  stage the agency's stored order is kept once it has reordered in the
+  dashboard; otherwise the canonical order. **`groupSectionsByStage`**
+  returns the beats the case study actually has, numbered in order, each
+  with its sections; a stage with nothing in it is left out.
+- **`caseStudyStageStatus(sections)`** reports all four stages, complete
+  only when the stage's core section (`STAGE_CORE_SECTION`: challenges,
+  strategy, performance, results) is present, with one sentence on what's
+  missing. The dashboard shows it beside the editor.
+- **Stage names.** The ids are fixed; what people see isn't. An agency
+  names the four stages once in the dashboard ("Heat", "Shape", "Temper",
+  "Finish") and `CaseStudyStageNames` carries that map to the editor, the
+  public portfolio config and the agency's site. `stageName(names, stage)`
+  reads it with the generic name as the fallback; `stageNamesProblems`
+  validates it and `STAGE_NAME_MAX_CHARS` caps each name.
+- **`CaseStudyNarrative`** is what the story says above its sections: one
+  `thesis` and one lede per stage, written for this project. Signal writes
+  it from the evidence it was given and the agency edits it;
+  `narrativeProblems` validates one and `CASE_STUDY_NARRATIVE_JSON_SCHEMA`
+  is the same rule as a schema. An absent narrative passes, so renderers
+  fall back to house copy for older case studies.
+- **The thread.** A challenge carries an `id` (`challengeId(n)` mints
+  "c1", "c2"…), a strategy phase says which challenges it `resolves`, a
+  result says which it `proves`. `caseStudyFlowProblems({ challenges,
+  phases, results })` names every challenge nothing resolves or proves and
+  every dangling reference. It judges links only where ids were written, so
+  content from before the thread passes.
+
 ## Why it exists
 
 A rule that lives in several copies is how two of them end up disagreeing.

package/dist/portfolio.d.ts

@@ -26,6 +26,176 @@ export interface FrameReadyMessage {
 export declare function isFrameReadyMessage(data: unknown): data is FrameReadyMessage;
 /** Bump on breaking changes to the collapse policy. */
 export declare const PORTFOLIO_CONTRACT_VERSION: 1;
+/** The four beats, in reading order. */
+export declare const CASE_STUDY_STAGES: readonly ['problem', 'build', 'proof', 'outcome'];
+export type CaseStudyStage = (typeof CASE_STUDY_STAGES)[number];
+/** The generic name of each beat and the question its sections answer. */
+export declare const CASE_STUDY_STAGE_COPY: Record<CaseStudyStage, {
+    name: string;
+    question: string;
+}>;
+/**
+ * An agency's own names for the four stages ("Heat", "Shape", "Temper",
+ * "Finish"), set once in the dashboard and read everywhere a stage is named:
+ * the editor, the public portfolio config, the agency's site. A stage left
+ * unnamed falls back to its generic name. The ids never change; only what
+ * people see does.
+ */
+export type CaseStudyStageNames = Partial<Record<CaseStudyStage, string>>;
+/** The longest a stage name may run. It's a heading word, a rail label, a tab. */
+export declare const STAGE_NAME_MAX_CHARS = 24;
+/**
+ * What's wrong with a set of stage names, or an empty list. Absent passes
+ * (generic names); present must be an object of short text keyed by stage.
+ */
+export declare function stageNamesProblems(names: unknown): string[];
+/** The name a stage is shown under: the agency's own when set, else the generic one. */
+export declare function stageName(names: CaseStudyStageNames | null | undefined, stage: CaseStudyStage): string;
+/**
+ * Every section type a case study can hold, in canonical reading order:
+ * hero, then each stage's sections, then the two that aren't rendered as
+ * sections of the story (SEO metadata, the closing CTA). This is THE list;
+ * the Sonor API and agency-site-kit import it rather than keeping their own.
+ */
+export declare const PORTFOLIO_SECTION_TYPES: readonly ['portfolioHero', 'portfolioChallenges', 'portfolioBeforeAfter', 'portfolioStrategy', 'portfolioSiteArchitecture', 'portfolioDesignSystem', 'portfolioFeatureSpotlight', 'portfolioGallery', 'portfolioVideo', 'portfolioTechStack', 'portfolioPerformance', 'portfolioSpeedComparison', 'portfolioResults', 'portfolioMetricsTimeline', 'portfolioConversionFunnel', 'portfolioServices', 'portfolioTeam', 'portfolioTestimonial', 'portfolioDetails', 'portfolioSeo', 'portfolioCTA'];
+export type PortfolioSectionType = (typeof PORTFOLIO_SECTION_TYPES)[number];
+export declare function isPortfolioSectionType(value: unknown): value is PortfolioSectionType;
+/**
+ * Which stage each section belongs to. Null for the hero (it opens the page,
+ * above the story), SEO metadata (never rendered as a section) and the CTA
+ * (closes the page, after the story). Typed over every section type so a new
+ * type without a stage is a compile error, not a section that renders last.
+ */
+export declare const SECTION_STAGE: Record<PortfolioSectionType, CaseStudyStage | null>;
+/** The stage a section type belongs to, or null when it sits outside the story. Unknown types are null. */
+export declare function sectionStage(type: string): CaseStudyStage | null;
+/**
+ * The one section each stage can't do without. A stage with other sections
+ * but not this one is told so by {@link caseStudyStageStatus}: a proof stage
+ * that's only a speed comparison has no measurement of the finished build.
+ */
+export declare const STAGE_CORE_SECTION: Record<CaseStudyStage, PortfolioSectionType>;
+/**
+ * Canonical display order, derived from the list above so it can't disagree
+ * with the stages. Renderers sort by this when nobody has reordered; the
+ * dashboard's stored order only ever moves a section within its stage.
+ */
+export declare const PORTFOLIO_SECTION_ORDER: Record<PortfolioSectionType, number>;
+/** The least a section needs for the ordering helpers: its type. Anything else rides along. */
+export interface SectionLike {
+    sectionType: string;
+}
+/**
+ * The sections in the order the case study reads.
+ *
+ * The arc always wins: the hero, then problem, build, proof, outcome, then
+ * the CTA. Within a stage, the agency's own order is kept once it has
+ * reordered in the dashboard (`sectionsOrdered`); otherwise the canonical
+ * order. Before this, a reordered case study rendered in exactly its stored
+ * order, so Results could sit above Challenges and the page read backwards.
+ * Never mutates.
+ */
+export declare function orderSections<T extends SectionLike>(sections: readonly T[] | null | undefined, options?: {
+    sectionsOrdered?: boolean;
+}): T[];
+/** One beat of the story with the sections that tell it. */
+export interface CaseStudyStageGroup<T extends SectionLike = SectionLike> {
+    stage: CaseStudyStage;
+    /** 1-based position among the stages this case study actually has. */
+    index: number;
+    sections: T[];
+}
+/**
+ * The story's beats, in order, each with its sections in reading order
+ * ({@link orderSections}). A stage with no sections is left out and the
+ * numbering follows, so a software case study with nothing measured runs
+ * problem, build, outcome as 1, 2, 3. The hero, SEO and CTA aren't in any
+ * group; a renderer places them itself.
+ */
+export declare function groupSectionsByStage<T extends SectionLike>(sections: readonly T[] | null | undefined, options?: {
+    sectionsOrdered?: boolean;
+}): CaseStudyStageGroup<T>[];
+/** What each stage of a case study has and what it's missing. */
+export interface CaseStudyStageStatus {
+    stage: CaseStudyStage;
+    /** The section types present, in reading order. */
+    present: PortfolioSectionType[];
+    /** True when the stage's core section ({@link STAGE_CORE_SECTION}) is present. */
+    complete: boolean;
+    /** Null when complete; otherwise one sentence on what the stage is missing. */
+    missing: string | null;
+}
+/**
+ * Each stage's status, all four, in order, whether or not the case study has
+ * sections in it. The dashboard shows these beside the editor so an empty
+ * proof stage is seen before the case study is published, not after.
+ */
+export declare function caseStudyStageStatus(sections: readonly SectionLike[] | null | undefined): CaseStudyStageStatus[];
+export interface CaseStudyNarrative {
+    /** One sentence: what this project was, in the end. */
+    thesis: string;
+    /** One or two sentences opening each stage, specific to this project. A stage may be left unwritten. */
+    stages: Partial<Record<CaseStudyStage, string>>;
+}
+/** The longest a thesis or a stage lede may run. Longer is a paragraph, and the sections are the paragraphs. */
+export declare const NARRATIVE_MAX_CHARS = 320;
+/**
+ * What's wrong with a narrative, or an empty list when nothing is. An absent
+ * narrative is legacy data and passes (renderers fall back to house copy);
+ * one that's present must be prose, under the length, with no unknown stage.
+ */
+export declare function narrativeProblems(narrative: unknown): string[];
+/** Agent-native contract: JSON Schema for {@link CaseStudyNarrative}. */
+export declare const CASE_STUDY_NARRATIVE_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/case-study-narrative.v1.json';
+    readonly title: 'CaseStudyNarrative';
+    readonly description: 'The thesis of a case study and the lede that opens each of its four stages.';
+    readonly type: 'object';
+    readonly required: readonly ['thesis'];
+    readonly properties: {
+        readonly thesis: {
+            readonly type: 'string';
+            readonly minLength: 1;
+            readonly maxLength: 320;
+        };
+        readonly stages: {
+            readonly type: 'object';
+            readonly properties: {
+                [k: string]: {
+                    type: string;
+                    maxLength: number;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+    readonly additionalProperties: false;
+};
+export interface ChallengeLike {
+    id?: string | null;
+    title?: string;
+}
+export interface PhaseLike {
+    resolves?: readonly string[] | null;
+}
+export interface ResultLike {
+    proves?: readonly string[] | null;
+}
+/** A stable id for the n-th challenge (1-based): "c1", "c2"… Writers that don't mint their own use this. */
+export declare function challengeId(position: number): string;
+/**
+ * The problems with how a case study's story hangs together, each one
+ * sentence, or an empty list. Read by the generator's audit and the
+ * dashboard. It judges links only where they've been written: a case study
+ * whose challenges carry no ids has nothing to check and passes, so legacy
+ * content isn't failed for predating the thread.
+ */
+export declare function caseStudyFlowProblems(input: {
+    challenges?: readonly ChallengeLike[] | null;
+    phases?: readonly PhaseLike[] | null;
+    results?: readonly ResultLike[] | null;
+}): string[];
 /** Minimal KPI shape the policy reads — callers pass their own richer tiles. */
 export interface KpiLike {
     label: string;

package/dist/portfolio.js

@@ -6,6 +6,236 @@ function isFrameReadyMessage(data) {
   return !!data && typeof data === "object" && data.type === FRAME_READY_MESSAGE && data.v === 1;
 }
 var PORTFOLIO_CONTRACT_VERSION = 1;
+var CASE_STUDY_STAGES = ["problem", "build", "proof", "outcome"];
+var CASE_STUDY_STAGE_COPY = {
+  problem: { name: "The problem", question: "What did the client come in with, and what was in the way?" },
+  build: { name: "The build", question: "What did we plan and make, and out of what?" },
+  proof: { name: "The proof", question: "How does the finished build hold up when measured?" },
+  outcome: { name: "The outcome", question: "What is the work doing for the client now?" }
+};
+var STAGE_NAME_MAX_CHARS = 24;
+function stageNamesProblems(names) {
+  if (names === void 0 || names === null) return [];
+  if (typeof names !== "object" || Array.isArray(names)) return ["stageNames must be an object"];
+  const problems = [];
+  for (const [stage, name] of Object.entries(names)) {
+    if (!CASE_STUDY_STAGES.includes(stage)) problems.push(`stageNames.${stage} is not a stage`);
+    else if (name === void 0 || name === null) continue;
+    else if (typeof name !== "string") problems.push(`stageNames.${stage} must be text`);
+    else if (name.trim().length > STAGE_NAME_MAX_CHARS)
+      problems.push(`stageNames.${stage} is over ${STAGE_NAME_MAX_CHARS} characters`);
+  }
+  return problems;
+}
+function stageName(names, stage) {
+  const own = names?.[stage]?.trim();
+  return own || CASE_STUDY_STAGE_COPY[stage].name;
+}
+var PORTFOLIO_SECTION_TYPES = [
+  "portfolioHero",
+  // problem
+  "portfolioChallenges",
+  "portfolioBeforeAfter",
+  // build
+  "portfolioStrategy",
+  "portfolioSiteArchitecture",
+  "portfolioDesignSystem",
+  "portfolioFeatureSpotlight",
+  "portfolioGallery",
+  "portfolioVideo",
+  "portfolioTechStack",
+  // proof
+  "portfolioPerformance",
+  "portfolioSpeedComparison",
+  // outcome
+  "portfolioResults",
+  "portfolioMetricsTimeline",
+  "portfolioConversionFunnel",
+  "portfolioServices",
+  "portfolioTeam",
+  "portfolioTestimonial",
+  "portfolioDetails",
+  // outside the story
+  "portfolioSeo",
+  "portfolioCTA"
+];
+function isPortfolioSectionType(value) {
+  return typeof value === "string" && PORTFOLIO_SECTION_TYPES.includes(value);
+}
+var SECTION_STAGE = {
+  portfolioHero: null,
+  portfolioChallenges: "problem",
+  portfolioBeforeAfter: "problem",
+  portfolioStrategy: "build",
+  portfolioSiteArchitecture: "build",
+  portfolioDesignSystem: "build",
+  portfolioFeatureSpotlight: "build",
+  portfolioGallery: "build",
+  portfolioVideo: "build",
+  portfolioTechStack: "build",
+  portfolioPerformance: "proof",
+  portfolioSpeedComparison: "proof",
+  portfolioResults: "outcome",
+  portfolioMetricsTimeline: "outcome",
+  portfolioConversionFunnel: "outcome",
+  portfolioServices: "outcome",
+  portfolioTeam: "outcome",
+  portfolioTestimonial: "outcome",
+  portfolioDetails: "outcome",
+  portfolioSeo: null,
+  portfolioCTA: null
+};
+function sectionStage(type) {
+  return isPortfolioSectionType(type) ? SECTION_STAGE[type] : null;
+}
+var STAGE_CORE_SECTION = {
+  problem: "portfolioChallenges",
+  build: "portfolioStrategy",
+  proof: "portfolioPerformance",
+  outcome: "portfolioResults"
+};
+var PORTFOLIO_SECTION_ORDER = Object.fromEntries(
+  PORTFOLIO_SECTION_TYPES.map((type, i) => [type, i])
+);
+var UNKNOWN_SECTION_ORDER = PORTFOLIO_SECTION_TYPES.length;
+function sectionOrder(type) {
+  return isPortfolioSectionType(type) ? PORTFOLIO_SECTION_ORDER[type] : UNKNOWN_SECTION_ORDER;
+}
+function stageOrder(type) {
+  if (type === "portfolioHero") return -1;
+  const stage = sectionStage(type);
+  return stage ? CASE_STUDY_STAGES.indexOf(stage) : CASE_STUDY_STAGES.length;
+}
+function orderSections(sections, options = {}) {
+  const list = [...sections ?? []];
+  const byStage = list.map((section, index) => ({ section, index }));
+  byStage.sort((a, b) => {
+    const stage = stageOrder(a.section.sectionType) - stageOrder(b.section.sectionType);
+    if (stage !== 0) return stage;
+    if (options.sectionsOrdered) return a.index - b.index;
+    const order = sectionOrder(a.section.sectionType) - sectionOrder(b.section.sectionType);
+    return order !== 0 ? order : a.index - b.index;
+  });
+  return byStage.map((s) => s.section);
+}
+function groupSectionsByStage(sections, options = {}) {
+  const ordered = orderSections(sections, options);
+  const groups = [];
+  for (const stage of CASE_STUDY_STAGES) {
+    const own = ordered.filter((s) => sectionStage(s.sectionType) === stage);
+    if (own.length) groups.push({ stage, index: groups.length + 1, sections: own });
+  }
+  return groups;
+}
+var STAGE_MISSING_COPY = {
+  problem: {
+    empty: "Nothing says what the client came in with. Add the challenges.",
+    noCore: "The problem is pictured but not stated. Add the challenges."
+  },
+  build: {
+    empty: "Nothing says what was planned or built. Add the strategy.",
+    noCore: "The build is shown but the plan behind it is missing. Add the strategy."
+  },
+  proof: {
+    empty: "Nothing measures the finished build. Add a performance measurement.",
+    noCore: "The old site is compared but the finished build has no measurement of its own. Add a performance measurement."
+  },
+  outcome: {
+    empty: "Nothing says what the work is doing for the client. Add the results.",
+    noCore: "The outcome has supporting sections but no results. Add the results."
+  }
+};
+function caseStudyStageStatus(sections) {
+  const ordered = orderSections(sections);
+  return CASE_STUDY_STAGES.map((stage) => {
+    const present = ordered.map((s) => s.sectionType).filter((t) => isPortfolioSectionType(t) && SECTION_STAGE[t] === stage);
+    const complete = present.includes(STAGE_CORE_SECTION[stage]);
+    const copy = STAGE_MISSING_COPY[stage];
+    return {
+      stage,
+      present,
+      complete,
+      missing: complete ? null : present.length ? copy.noCore : copy.empty
+    };
+  });
+}
+var NARRATIVE_MAX_CHARS = 320;
+function narrativeProblems(narrative) {
+  if (narrative === void 0 || narrative === null) return [];
+  if (typeof narrative !== "object") return ["narrative must be an object"];
+  const problems = [];
+  const n = narrative;
+  if (typeof n.thesis !== "string" || !n.thesis.trim()) problems.push("narrative.thesis is required");
+  else if (n.thesis.length > NARRATIVE_MAX_CHARS) problems.push(`narrative.thesis is over ${NARRATIVE_MAX_CHARS} characters`);
+  if (n.stages === void 0 || n.stages === null) return problems;
+  if (typeof n.stages !== "object") return [...problems, "narrative.stages must be an object"];
+  for (const [stage, lede] of Object.entries(n.stages)) {
+    if (!CASE_STUDY_STAGES.includes(stage)) {
+      problems.push(`narrative.stages.${stage} is not a stage (${CASE_STUDY_STAGES.join(", ")})`);
+      continue;
+    }
+    if (lede === void 0 || lede === null) continue;
+    if (typeof lede !== "string") problems.push(`narrative.stages.${stage} must be text`);
+    else if (lede.length > NARRATIVE_MAX_CHARS) problems.push(`narrative.stages.${stage} is over ${NARRATIVE_MAX_CHARS} characters`);
+  }
+  return problems;
+}
+var CASE_STUDY_NARRATIVE_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/case-study-narrative.v1.json",
+  title: "CaseStudyNarrative",
+  description: "The thesis of a case study and the lede that opens each of its four stages.",
+  type: "object",
+  required: ["thesis"],
+  properties: {
+    thesis: { type: "string", minLength: 1, maxLength: NARRATIVE_MAX_CHARS },
+    stages: {
+      type: "object",
+      properties: Object.fromEntries(
+        CASE_STUDY_STAGES.map((stage) => [stage, { type: "string", maxLength: NARRATIVE_MAX_CHARS }])
+      ),
+      additionalProperties: false
+    }
+  },
+  additionalProperties: false
+};
+function challengeId(position) {
+  return `c${position}`;
+}
+function caseStudyFlowProblems(input) {
+  const challenges = input.challenges ?? [];
+  const ids = challenges.map((c) => typeof c.id === "string" && c.id.trim() ? c.id.trim() : null);
+  if (!ids.some(Boolean)) return [];
+  const problems = [];
+  const known = new Set(ids.filter((id) => !!id));
+  if (known.size !== ids.filter(Boolean).length) problems.push("two challenges share an id");
+  ids.forEach((id, i) => {
+    if (!id) problems.push(`challenge ${i + 1} has no id while the others do`);
+  });
+  const resolved = /* @__PURE__ */ new Set();
+  const proven = /* @__PURE__ */ new Set();
+  for (const phase of input.phases ?? []) {
+    for (const ref of phase.resolves ?? []) {
+      if (!known.has(ref)) problems.push(`a strategy phase resolves "${ref}", which is not a challenge`);
+      else resolved.add(ref);
+    }
+  }
+  for (const result of input.results ?? []) {
+    for (const ref of result.proves ?? []) {
+      if (!known.has(ref)) problems.push(`a result proves "${ref}", which is not a challenge`);
+      else proven.add(ref);
+    }
+  }
+  const nameOf = (id) => {
+    const c = challenges.find((x) => x.id === id);
+    return c?.title?.trim() ? `"${c.title.trim()}"` : id;
+  };
+  for (const id of known) {
+    if (!resolved.has(id)) problems.push(`no strategy phase resolves challenge ${nameOf(id)}`);
+    if (!proven.has(id)) problems.push(`no result proves challenge ${nameOf(id)}`);
+  }
+  return problems;
+}
 var LIGHTHOUSE_RE = /lighthouse/i;
 function isLighthouseKpi(kpi) {
   return LIGHTHOUSE_RE.test(kpi.label || "");
@@ -113,17 +343,36 @@ function carryReportedMetrics(previous, next, keyOf) {
   return [...reported, ...generated];
 }
 
+exports.CASE_STUDY_NARRATIVE_JSON_SCHEMA = CASE_STUDY_NARRATIVE_JSON_SCHEMA;
+exports.CASE_STUDY_STAGES = CASE_STUDY_STAGES;
+exports.CASE_STUDY_STAGE_COPY = CASE_STUDY_STAGE_COPY;
 exports.FRAME_READY_MESSAGE = FRAME_READY_MESSAGE;
 exports.METRIC_SOURCES = METRIC_SOURCES;
+exports.NARRATIVE_MAX_CHARS = NARRATIVE_MAX_CHARS;
 exports.PORTFOLIO_CONTRACT_VERSION = PORTFOLIO_CONTRACT_VERSION;
 exports.PORTFOLIO_KPI_JSON_SCHEMA = PORTFOLIO_KPI_JSON_SCHEMA;
+exports.PORTFOLIO_SECTION_ORDER = PORTFOLIO_SECTION_ORDER;
+exports.PORTFOLIO_SECTION_TYPES = PORTFOLIO_SECTION_TYPES;
+exports.SECTION_STAGE = SECTION_STAGE;
+exports.STAGE_CORE_SECTION = STAGE_CORE_SECTION;
+exports.STAGE_NAME_MAX_CHARS = STAGE_NAME_MAX_CHARS;
 exports.carryReportedMetrics = carryReportedMetrics;
+exports.caseStudyFlowProblems = caseStudyFlowProblems;
+exports.caseStudyStageStatus = caseStudyStageStatus;
+exports.challengeId = challengeId;
 exports.curateHeroKpis = curateHeroKpis;
 exports.formatAttribution = formatAttribution;
+exports.groupSectionsByStage = groupSectionsByStage;
 exports.isFrameReadyMessage = isFrameReadyMessage;
 exports.isHeadlineMetric = isHeadlineMetric;
 exports.isLighthouseKpi = isLighthouseKpi;
 exports.isMetricSource = isMetricSource;
+exports.isPortfolioSectionType = isPortfolioSectionType;
 exports.metricSourceLabel = metricSourceLabel;
 exports.metricSourceProblem = metricSourceProblem;
+exports.narrativeProblems = narrativeProblems;
+exports.orderSections = orderSections;
+exports.sectionStage = sectionStage;
 exports.shortAttribution = shortAttribution;
+exports.stageName = stageName;
+exports.stageNamesProblems = stageNamesProblems;

package/dist/portfolio.mjs

@@ -4,6 +4,236 @@ function isFrameReadyMessage(data) {
   return !!data && typeof data === "object" && data.type === FRAME_READY_MESSAGE && data.v === 1;
 }
 var PORTFOLIO_CONTRACT_VERSION = 1;
+var CASE_STUDY_STAGES = ["problem", "build", "proof", "outcome"];
+var CASE_STUDY_STAGE_COPY = {
+  problem: { name: "The problem", question: "What did the client come in with, and what was in the way?" },
+  build: { name: "The build", question: "What did we plan and make, and out of what?" },
+  proof: { name: "The proof", question: "How does the finished build hold up when measured?" },
+  outcome: { name: "The outcome", question: "What is the work doing for the client now?" }
+};
+var STAGE_NAME_MAX_CHARS = 24;
+function stageNamesProblems(names) {
+  if (names === void 0 || names === null) return [];
+  if (typeof names !== "object" || Array.isArray(names)) return ["stageNames must be an object"];
+  const problems = [];
+  for (const [stage, name] of Object.entries(names)) {
+    if (!CASE_STUDY_STAGES.includes(stage)) problems.push(`stageNames.${stage} is not a stage`);
+    else if (name === void 0 || name === null) continue;
+    else if (typeof name !== "string") problems.push(`stageNames.${stage} must be text`);
+    else if (name.trim().length > STAGE_NAME_MAX_CHARS)
+      problems.push(`stageNames.${stage} is over ${STAGE_NAME_MAX_CHARS} characters`);
+  }
+  return problems;
+}
+function stageName(names, stage) {
+  const own = names?.[stage]?.trim();
+  return own || CASE_STUDY_STAGE_COPY[stage].name;
+}
+var PORTFOLIO_SECTION_TYPES = [
+  "portfolioHero",
+  // problem
+  "portfolioChallenges",
+  "portfolioBeforeAfter",
+  // build
+  "portfolioStrategy",
+  "portfolioSiteArchitecture",
+  "portfolioDesignSystem",
+  "portfolioFeatureSpotlight",
+  "portfolioGallery",
+  "portfolioVideo",
+  "portfolioTechStack",
+  // proof
+  "portfolioPerformance",
+  "portfolioSpeedComparison",
+  // outcome
+  "portfolioResults",
+  "portfolioMetricsTimeline",
+  "portfolioConversionFunnel",
+  "portfolioServices",
+  "portfolioTeam",
+  "portfolioTestimonial",
+  "portfolioDetails",
+  // outside the story
+  "portfolioSeo",
+  "portfolioCTA"
+];
+function isPortfolioSectionType(value) {
+  return typeof value === "string" && PORTFOLIO_SECTION_TYPES.includes(value);
+}
+var SECTION_STAGE = {
+  portfolioHero: null,
+  portfolioChallenges: "problem",
+  portfolioBeforeAfter: "problem",
+  portfolioStrategy: "build",
+  portfolioSiteArchitecture: "build",
+  portfolioDesignSystem: "build",
+  portfolioFeatureSpotlight: "build",
+  portfolioGallery: "build",
+  portfolioVideo: "build",
+  portfolioTechStack: "build",
+  portfolioPerformance: "proof",
+  portfolioSpeedComparison: "proof",
+  portfolioResults: "outcome",
+  portfolioMetricsTimeline: "outcome",
+  portfolioConversionFunnel: "outcome",
+  portfolioServices: "outcome",
+  portfolioTeam: "outcome",
+  portfolioTestimonial: "outcome",
+  portfolioDetails: "outcome",
+  portfolioSeo: null,
+  portfolioCTA: null
+};
+function sectionStage(type) {
+  return isPortfolioSectionType(type) ? SECTION_STAGE[type] : null;
+}
+var STAGE_CORE_SECTION = {
+  problem: "portfolioChallenges",
+  build: "portfolioStrategy",
+  proof: "portfolioPerformance",
+  outcome: "portfolioResults"
+};
+var PORTFOLIO_SECTION_ORDER = Object.fromEntries(
+  PORTFOLIO_SECTION_TYPES.map((type, i) => [type, i])
+);
+var UNKNOWN_SECTION_ORDER = PORTFOLIO_SECTION_TYPES.length;
+function sectionOrder(type) {
+  return isPortfolioSectionType(type) ? PORTFOLIO_SECTION_ORDER[type] : UNKNOWN_SECTION_ORDER;
+}
+function stageOrder(type) {
+  if (type === "portfolioHero") return -1;
+  const stage = sectionStage(type);
+  return stage ? CASE_STUDY_STAGES.indexOf(stage) : CASE_STUDY_STAGES.length;
+}
+function orderSections(sections, options = {}) {
+  const list = [...sections ?? []];
+  const byStage = list.map((section, index) => ({ section, index }));
+  byStage.sort((a, b) => {
+    const stage = stageOrder(a.section.sectionType) - stageOrder(b.section.sectionType);
+    if (stage !== 0) return stage;
+    if (options.sectionsOrdered) return a.index - b.index;
+    const order = sectionOrder(a.section.sectionType) - sectionOrder(b.section.sectionType);
+    return order !== 0 ? order : a.index - b.index;
+  });
+  return byStage.map((s) => s.section);
+}
+function groupSectionsByStage(sections, options = {}) {
+  const ordered = orderSections(sections, options);
+  const groups = [];
+  for (const stage of CASE_STUDY_STAGES) {
+    const own = ordered.filter((s) => sectionStage(s.sectionType) === stage);
+    if (own.length) groups.push({ stage, index: groups.length + 1, sections: own });
+  }
+  return groups;
+}
+var STAGE_MISSING_COPY = {
+  problem: {
+    empty: "Nothing says what the client came in with. Add the challenges.",
+    noCore: "The problem is pictured but not stated. Add the challenges."
+  },
+  build: {
+    empty: "Nothing says what was planned or built. Add the strategy.",
+    noCore: "The build is shown but the plan behind it is missing. Add the strategy."
+  },
+  proof: {
+    empty: "Nothing measures the finished build. Add a performance measurement.",
+    noCore: "The old site is compared but the finished build has no measurement of its own. Add a performance measurement."
+  },
+  outcome: {
+    empty: "Nothing says what the work is doing for the client. Add the results.",
+    noCore: "The outcome has supporting sections but no results. Add the results."
+  }
+};
+function caseStudyStageStatus(sections) {
+  const ordered = orderSections(sections);
+  return CASE_STUDY_STAGES.map((stage) => {
+    const present = ordered.map((s) => s.sectionType).filter((t) => isPortfolioSectionType(t) && SECTION_STAGE[t] === stage);
+    const complete = present.includes(STAGE_CORE_SECTION[stage]);
+    const copy = STAGE_MISSING_COPY[stage];
+    return {
+      stage,
+      present,
+      complete,
+      missing: complete ? null : present.length ? copy.noCore : copy.empty
+    };
+  });
+}
+var NARRATIVE_MAX_CHARS = 320;
+function narrativeProblems(narrative) {
+  if (narrative === void 0 || narrative === null) return [];
+  if (typeof narrative !== "object") return ["narrative must be an object"];
+  const problems = [];
+  const n = narrative;
+  if (typeof n.thesis !== "string" || !n.thesis.trim()) problems.push("narrative.thesis is required");
+  else if (n.thesis.length > NARRATIVE_MAX_CHARS) problems.push(`narrative.thesis is over ${NARRATIVE_MAX_CHARS} characters`);
+  if (n.stages === void 0 || n.stages === null) return problems;
+  if (typeof n.stages !== "object") return [...problems, "narrative.stages must be an object"];
+  for (const [stage, lede] of Object.entries(n.stages)) {
+    if (!CASE_STUDY_STAGES.includes(stage)) {
+      problems.push(`narrative.stages.${stage} is not a stage (${CASE_STUDY_STAGES.join(", ")})`);
+      continue;
+    }
+    if (lede === void 0 || lede === null) continue;
+    if (typeof lede !== "string") problems.push(`narrative.stages.${stage} must be text`);
+    else if (lede.length > NARRATIVE_MAX_CHARS) problems.push(`narrative.stages.${stage} is over ${NARRATIVE_MAX_CHARS} characters`);
+  }
+  return problems;
+}
+var CASE_STUDY_NARRATIVE_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/case-study-narrative.v1.json",
+  title: "CaseStudyNarrative",
+  description: "The thesis of a case study and the lede that opens each of its four stages.",
+  type: "object",
+  required: ["thesis"],
+  properties: {
+    thesis: { type: "string", minLength: 1, maxLength: NARRATIVE_MAX_CHARS },
+    stages: {
+      type: "object",
+      properties: Object.fromEntries(
+        CASE_STUDY_STAGES.map((stage) => [stage, { type: "string", maxLength: NARRATIVE_MAX_CHARS }])
+      ),
+      additionalProperties: false
+    }
+  },
+  additionalProperties: false
+};
+function challengeId(position) {
+  return `c${position}`;
+}
+function caseStudyFlowProblems(input) {
+  const challenges = input.challenges ?? [];
+  const ids = challenges.map((c) => typeof c.id === "string" && c.id.trim() ? c.id.trim() : null);
+  if (!ids.some(Boolean)) return [];
+  const problems = [];
+  const known = new Set(ids.filter((id) => !!id));
+  if (known.size !== ids.filter(Boolean).length) problems.push("two challenges share an id");
+  ids.forEach((id, i) => {
+    if (!id) problems.push(`challenge ${i + 1} has no id while the others do`);
+  });
+  const resolved = /* @__PURE__ */ new Set();
+  const proven = /* @__PURE__ */ new Set();
+  for (const phase of input.phases ?? []) {
+    for (const ref of phase.resolves ?? []) {
+      if (!known.has(ref)) problems.push(`a strategy phase resolves "${ref}", which is not a challenge`);
+      else resolved.add(ref);
+    }
+  }
+  for (const result of input.results ?? []) {
+    for (const ref of result.proves ?? []) {
+      if (!known.has(ref)) problems.push(`a result proves "${ref}", which is not a challenge`);
+      else proven.add(ref);
+    }
+  }
+  const nameOf = (id) => {
+    const c = challenges.find((x) => x.id === id);
+    return c?.title?.trim() ? `"${c.title.trim()}"` : id;
+  };
+  for (const id of known) {
+    if (!resolved.has(id)) problems.push(`no strategy phase resolves challenge ${nameOf(id)}`);
+    if (!proven.has(id)) problems.push(`no result proves challenge ${nameOf(id)}`);
+  }
+  return problems;
+}
 var LIGHTHOUSE_RE = /lighthouse/i;
 function isLighthouseKpi(kpi) {
   return LIGHTHOUSE_RE.test(kpi.label || "");
@@ -111,4 +341,4 @@ function carryReportedMetrics(previous, next, keyOf) {
   return [...reported, ...generated];
 }
 
-export { FRAME_READY_MESSAGE, METRIC_SOURCES, PORTFOLIO_CONTRACT_VERSION, PORTFOLIO_KPI_JSON_SCHEMA, carryReportedMetrics, curateHeroKpis, formatAttribution, isFrameReadyMessage, isHeadlineMetric, isLighthouseKpi, isMetricSource, metricSourceLabel, metricSourceProblem, shortAttribution };
+export { CASE_STUDY_NARRATIVE_JSON_SCHEMA, CASE_STUDY_STAGES, CASE_STUDY_STAGE_COPY, FRAME_READY_MESSAGE, METRIC_SOURCES, NARRATIVE_MAX_CHARS, PORTFOLIO_CONTRACT_VERSION, PORTFOLIO_KPI_JSON_SCHEMA, PORTFOLIO_SECTION_ORDER, PORTFOLIO_SECTION_TYPES, SECTION_STAGE, STAGE_CORE_SECTION, STAGE_NAME_MAX_CHARS, carryReportedMetrics, caseStudyFlowProblems, caseStudyStageStatus, challengeId, curateHeroKpis, formatAttribution, groupSectionsByStage, isFrameReadyMessage, isHeadlineMetric, isLighthouseKpi, isMetricSource, isPortfolioSectionType, metricSourceLabel, metricSourceProblem, narrativeProblems, orderSections, sectionStage, shortAttribution, stageName, stageNamesProblems };

package/dist/public-url-host.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The shared literal-host SSRF policy. Pass URL.hostname (which canonicalizes
+ * numeric IPv4 spellings), or an address returned by a DNS lookup. IPv6 may
+ * have the brackets URL.hostname retains. This isn't a URL validator and
+ * doesn't trim input, resolve DNS, follow redirects or open a connection.
+ * Callers still enforce their protocol/port rules and check or pin the DNS
+ * addresses used by each connection; a false result alone can't prove a
+ * destination is public.
+ */
+export declare function isBlockedPublicUrlHost(rawHost: string): boolean;

package/dist/public-url-host.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// src/contracts/public-url-host.ts
+function isPrivateIpv4(a, b) {
+  return a === 127 || a === 10 || a === 0 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127 || a >= 224;
+}
+function ipv6Words(host) {
+  if (!host.includes(":") || !/^[a-f\d:.]+$/.test(host)) return null;
+  let canonical;
+  try {
+    canonical = new URL(`http://[${host}]/`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const sides = canonical.split("::");
+  const left = sides[0] ? sides[0].split(":") : [];
+  const right = sides.length > 1 && sides[1] ? sides[1].split(":") : [];
+  return [...left, ...Array(sides.length > 1 ? 8 - left.length - right.length : 0).fill("0"), ...right].map((word) => parseInt(word, 16));
+}
+function isBlockedPublicUrlHost(rawHost) {
+  const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
+  const blockedName = host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal");
+  if (host.includes(":") && host.includes("%")) return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  const blockedIp = !!ipv4 && isPrivateIpv4(Number(ipv4[1]), Number(ipv4[2]));
+  const words = ipv6Words(host);
+  const blockedIpv6 = !!words && // Unspecified/loopback, unique-local, link-local, deprecated site-local
+  // and multicast destinations aren't public logo/webhook endpoints.
+  (words.every((word) => word === 0) || words.slice(0, 7).every((word) => word === 0) && words[7] === 1 || (words[0] & 65024) === 64512 || (words[0] & 65472) === 65152 || (words[0] & 65472) === 65216 || (words[0] & 65280) === 65280 || // IPv4-mapped and older IPv4-compatible forms carry an IPv4 destination.
+  words.slice(0, 5).every((word) => word === 0) && [0, 65535].includes(words[5]) && isPrivateIpv4(words[6] >> 8, words[6] & 255));
+  return blockedName || blockedIp || blockedIpv6;
+}
+
+exports.isBlockedPublicUrlHost = isBlockedPublicUrlHost;

package/dist/public-url-host.mjs

@@ -0,0 +1,32 @@
+// src/contracts/public-url-host.ts
+function isPrivateIpv4(a, b) {
+  return a === 127 || a === 10 || a === 0 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127 || a >= 224;
+}
+function ipv6Words(host) {
+  if (!host.includes(":") || !/^[a-f\d:.]+$/.test(host)) return null;
+  let canonical;
+  try {
+    canonical = new URL(`http://[${host}]/`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const sides = canonical.split("::");
+  const left = sides[0] ? sides[0].split(":") : [];
+  const right = sides.length > 1 && sides[1] ? sides[1].split(":") : [];
+  return [...left, ...Array(sides.length > 1 ? 8 - left.length - right.length : 0).fill("0"), ...right].map((word) => parseInt(word, 16));
+}
+function isBlockedPublicUrlHost(rawHost) {
+  const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
+  const blockedName = host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal");
+  if (host.includes(":") && host.includes("%")) return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  const blockedIp = !!ipv4 && isPrivateIpv4(Number(ipv4[1]), Number(ipv4[2]));
+  const words = ipv6Words(host);
+  const blockedIpv6 = !!words && // Unspecified/loopback, unique-local, link-local, deprecated site-local
+  // and multicast destinations aren't public logo/webhook endpoints.
+  (words.every((word) => word === 0) || words.slice(0, 7).every((word) => word === 0) && words[7] === 1 || (words[0] & 65024) === 64512 || (words[0] & 65472) === 65152 || (words[0] & 65472) === 65216 || (words[0] & 65280) === 65280 || // IPv4-mapped and older IPv4-compatible forms carry an IPv4 destination.
+  words.slice(0, 5).every((word) => word === 0) && [0, 65535].includes(words[5]) && isPrivateIpv4(words[6] >> 8, words[6] & 255));
+  return blockedName || blockedIp || blockedIpv6;
+}
+
+export { isBlockedPublicUrlHost };

package/dist/publication-branding.d.ts

@@ -107,7 +107,7 @@ export interface PublicationBrandingValidatorOptions {
     /**
      * True when a URL's hostname must never be stored as a logo or publisher
      * URL: loopback, private and link-local ranges, `localhost` and the like.
-     * Each API passes its own server-side SSRF host guard. It receives
+     * Each API passes the shared `public-url-host` policy. It receives
      * `new URL(value).hostname`, so IPv6 keeps its brackets.
      */
     isBlockedHost: (hostname: string) => boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.10.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, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, and what a publication's branding may hold. Pure functions, no dependencies.",
+  "version": "2.12.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, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, what a publication's branding may hold, and which literal hosts are refused as public fetch destinations. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -141,6 +141,11 @@
       "types": "./dist/publication-branding.d.ts",
       "import": "./dist/publication-branding.mjs",
       "require": "./dist/publication-branding.js"
+    },
+    "./public-url-host": {
+      "types": "./dist/public-url-host.d.ts",
+      "import": "./dist/public-url-host.mjs",
+      "require": "./dist/public-url-host.js"
     }
   },
   "typesVersions": {