@sonordev/contracts 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2.13.0
+
+- Publication branding adds `editorial.focusClosingBackground`, with `planned_photo` and `article_atmosphere` choices. The setting inherits through publication and platform layers, and supports clearing an override. Article atmosphere closing frames reuse saved artwork and the real author portrait; other publications retain their existing behavior.
+
 ## 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.
@@ -7,7 +11,7 @@ A minor release: `@sonordev/contracts/portfolio` now holds the structure of a ca
 - **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.
+- **Stage names.** A site 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.
 

package/README.md

@@ -39,6 +39,15 @@ pnpm add @sonordev/contracts
 | `@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 |
 
+## Focus closing artwork
+
+`publication-branding` accepts `editorial.focusClosingBackground` at publication
+and platform levels. `planned_photo` keeps the planned closing image;
+`article_atmosphere` reuses the article's saved atmosphere with its real author
+portrait. Omitting the field keeps existing behavior. A patch value of `null`
+clears the override and restores inheritance. The article-atmosphere mode requires
+both saved sources; it doesn't invent a portrait or substitute unrelated artwork.
+
 ## Public URL hosts
 
 `isBlockedPublicUrlHost(host)` shares the APIs' loopback, private IPv4,
@@ -829,10 +838,10 @@ the dashboard that edits it and every site that renders it.
   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)`
+- **Stage names.** The ids are fixed; what people see isn't. A site names
+  the four stages in the dashboard ("Heat", "Shape", "Temper", "Finish"),
+  per project like the rest of its branding, and `CaseStudyStageNames`
+  carries that map to the editor, the public portfolio config and the 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

package/dist/portfolio.d.ts

@@ -35,11 +35,11 @@ export declare const CASE_STUDY_STAGE_COPY: Record<CaseStudyStage, {
     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.
+ * A site's own names for the four stages ("Heat", "Shape", "Temper",
+ * "Finish"), set per project in the dashboard (branding is per project) and
+ * read everywhere a stage is named: the editor, the public portfolio config,
+ * the site itself. 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. */
@@ -49,7 +49,7 @@ export declare const STAGE_NAME_MAX_CHARS = 24;
  * (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. */
+/** The name a stage is shown under: the site'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:

package/dist/publication-branding.d.ts

@@ -13,7 +13,8 @@ export declare const PUBLICATION_IDENTITY_FIELDS: readonly ['publicationName', '
 export declare const PUBLICATION_LOGO_VARIANTS: readonly ['default', 'light', 'dark'];
 export declare const PUBLICATION_COLOR_FIELDS: readonly ['primary', 'secondary', 'accent', 'background', 'surface', 'text', 'muted', 'border'];
 export declare const PUBLICATION_TYPOGRAPHY_FIELDS: readonly ['heading', 'body', 'mono', 'emailHeadingFallback', 'emailBodyFallback'];
-export declare const PUBLICATION_EDITORIAL_FIELDS: readonly ['articleStyle', 'cardLayout', 'charter', 'siteCharters'];
+export declare const PUBLICATION_EDITORIAL_FIELDS: readonly ['articleStyle', 'cardLayout', 'focusClosingBackground', 'charter', 'siteCharters'];
+export declare const FOCUS_CLOSING_BACKGROUNDS: readonly ['planned_photo', 'article_atmosphere'];
 export declare const PUBLICATION_NEWSLETTER_FIELDS: readonly ['name', 'tagline', 'layout', 'maxWidth'];
 /** Fonts every email client has, the only families an email fallback may name. Lowercase. */
 export declare const EMAIL_SAFE_FONTS: ReadonlySet<string>;
@@ -56,6 +57,8 @@ export interface PublicationEditorial {
     /** Shared Broadcast style for articles, reviews and generated posts; portfolio is excluded. Legacy wire name. */
     articleStyle?: BroadcastStyleId;
     cardLayout?: PublicationCardLayout;
+    /** Focus closing frames may reuse the article's saved atmosphere and real author portrait. */
+    focusClosingBackground?: (typeof FOCUS_CLOSING_BACKGROUNDS)[number];
 }
 export interface PublicationNewsletter {
     name?: string;

package/dist/publication-branding.js

@@ -138,7 +138,8 @@ var PUBLICATION_IDENTITY_FIELDS = ["publicationName", "wordmark", "tagline", "pu
 var PUBLICATION_LOGO_VARIANTS = ["default", "light", "dark"];
 var PUBLICATION_COLOR_FIELDS = ["primary", "secondary", "accent", "background", "surface", "text", "muted", "border"];
 var PUBLICATION_TYPOGRAPHY_FIELDS = ["heading", "body", "mono", "emailHeadingFallback", "emailBodyFallback"];
-var PUBLICATION_EDITORIAL_FIELDS = ["articleStyle", "cardLayout", "charter", "siteCharters"];
+var PUBLICATION_EDITORIAL_FIELDS = ["articleStyle", "cardLayout", "focusClosingBackground", "charter", "siteCharters"];
+var FOCUS_CLOSING_BACKGROUNDS = ["planned_photo", "article_atmosphere"];
 var PUBLICATION_NEWSLETTER_FIELDS = ["name", "tagline", "layout", "maxWidth"];
 var EMAIL_SAFE_FONTS = /* @__PURE__ */ new Set([
   "arial",
@@ -279,7 +280,7 @@ function createPublicationBrandingValidator(options) {
               throw new PublicationBrandingValidationError(`${prefix}.${key}`, error.message);
             }
           }
-          const allowed = key === "articleStyle" ? BROADCAST_STYLES : patch ? PUBLICATION_CARD_LAYOUTS : SAVED_PUBLICATION_CARD_LAYOUTS;
+          const allowed = key === "articleStyle" ? BROADCAST_STYLES : key === "focusClosingBackground" ? FOCUS_CLOSING_BACKGROUNDS : patch ? PUBLICATION_CARD_LAYOUTS : SAVED_PUBLICATION_CARD_LAYOUTS;
           if (typeof v !== "string" || !allowed.includes(v)) throw new PublicationBrandingValidationError(`${prefix}.${key}`, `choose ${allowed.join(", ")}`);
           return v;
         });
@@ -328,6 +329,7 @@ function createPublicationBrandingValidator(options) {
 }
 
 exports.EMAIL_SAFE_FONTS = EMAIL_SAFE_FONTS;
+exports.FOCUS_CLOSING_BACKGROUNDS = FOCUS_CLOSING_BACKGROUNDS;
 exports.GENERIC_FONT_FAMILIES = GENERIC_FONT_FAMILIES;
 exports.PUBLICATION_BRANDING_SECTIONS = PUBLICATION_BRANDING_SECTIONS;
 exports.PUBLICATION_BRANDING_VERSION = PUBLICATION_BRANDING_VERSION;

package/dist/publication-branding.mjs

@@ -136,7 +136,8 @@ var PUBLICATION_IDENTITY_FIELDS = ["publicationName", "wordmark", "tagline", "pu
 var PUBLICATION_LOGO_VARIANTS = ["default", "light", "dark"];
 var PUBLICATION_COLOR_FIELDS = ["primary", "secondary", "accent", "background", "surface", "text", "muted", "border"];
 var PUBLICATION_TYPOGRAPHY_FIELDS = ["heading", "body", "mono", "emailHeadingFallback", "emailBodyFallback"];
-var PUBLICATION_EDITORIAL_FIELDS = ["articleStyle", "cardLayout", "charter", "siteCharters"];
+var PUBLICATION_EDITORIAL_FIELDS = ["articleStyle", "cardLayout", "focusClosingBackground", "charter", "siteCharters"];
+var FOCUS_CLOSING_BACKGROUNDS = ["planned_photo", "article_atmosphere"];
 var PUBLICATION_NEWSLETTER_FIELDS = ["name", "tagline", "layout", "maxWidth"];
 var EMAIL_SAFE_FONTS = /* @__PURE__ */ new Set([
   "arial",
@@ -277,7 +278,7 @@ function createPublicationBrandingValidator(options) {
               throw new PublicationBrandingValidationError(`${prefix}.${key}`, error.message);
             }
           }
-          const allowed = key === "articleStyle" ? BROADCAST_STYLES : patch ? PUBLICATION_CARD_LAYOUTS : SAVED_PUBLICATION_CARD_LAYOUTS;
+          const allowed = key === "articleStyle" ? BROADCAST_STYLES : key === "focusClosingBackground" ? FOCUS_CLOSING_BACKGROUNDS : patch ? PUBLICATION_CARD_LAYOUTS : SAVED_PUBLICATION_CARD_LAYOUTS;
           if (typeof v !== "string" || !allowed.includes(v)) throw new PublicationBrandingValidationError(`${prefix}.${key}`, `choose ${allowed.join(", ")}`);
           return v;
         });
@@ -325,4 +326,4 @@ function createPublicationBrandingValidator(options) {
   };
 }
 
-export { EMAIL_SAFE_FONTS, GENERIC_FONT_FAMILIES, PUBLICATION_BRANDING_SECTIONS, PUBLICATION_BRANDING_VERSION, PUBLICATION_CHARTER_FIELDS, PUBLICATION_COLOR_FIELDS, PUBLICATION_EDITORIAL_FIELDS, PUBLICATION_IDENTITY_FIELDS, PUBLICATION_LOGO_VARIANTS, PUBLICATION_NEWSLETTER_FIELDS, PUBLICATION_PLATFORMS, PUBLICATION_TYPOGRAPHY_FIELDS, PublicationBrandingValidationError, containsControlCharacters, createPublicationBrandingValidator, mergePublicationBrandingLayers, parsePublicationCharter, parseSiteCharters, publicationCharterContext, publicationCharterFor, safeFontStack };
+export { EMAIL_SAFE_FONTS, FOCUS_CLOSING_BACKGROUNDS, GENERIC_FONT_FAMILIES, PUBLICATION_BRANDING_SECTIONS, PUBLICATION_BRANDING_VERSION, PUBLICATION_CHARTER_FIELDS, PUBLICATION_COLOR_FIELDS, PUBLICATION_EDITORIAL_FIELDS, PUBLICATION_IDENTITY_FIELDS, PUBLICATION_LOGO_VARIANTS, PUBLICATION_NEWSLETTER_FIELDS, PUBLICATION_PLATFORMS, PUBLICATION_TYPOGRAPHY_FIELDS, PublicationBrandingValidationError, containsControlCharacters, createPublicationBrandingValidator, mergePublicationBrandingLayers, parsePublicationCharter, parseSiteCharters, publicationCharterContext, publicationCharterFor, safeFontStack };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.12.0",
+  "version": "2.13.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": {