@anthusai/papyrus 1.3.0 → 1.4.0-next.1

package/lib/layout-plan.ts

@@ -469,7 +469,12 @@ export type LayoutRegionSpec = z.infer<typeof LayoutRegionSchema>;
 export type LayoutPageSpec = z.infer<typeof LayoutPageSchema>;
 export type EditionLayoutPlan = z.infer<typeof EditionLayoutPlanSchema>;
 
-export function createDefaultEditionLayoutPlan(itemIds: string[]): EditionLayoutPlan {
+export type ArticleCutPolicy = ArticleFrameBlockSpec["cutPolicy"];
+
+export function createDefaultEditionLayoutPlan(
+  itemIds: string[],
+  cutPoliciesByItemId: Record<string, ArticleCutPolicy> = {},
+): EditionLayoutPlan {
   const frontItemIds = getDefaultFrontItemOrder(itemIds);
   const frontBlocks = frontItemIds.map((itemId, index) => ({
     id: `front-${itemId}`,
@@ -563,7 +568,7 @@ export function createDefaultEditionLayoutPlan(itemIds: string[]): EditionLayout
           ],
         }
       : undefined,
-    cutPolicy: getDefaultCutPolicy(itemId),
+    cutPolicy: cutPoliciesByItemId[itemId],
   }));
 
   const plan: EditionLayoutPlan = normalizeEditionLayoutPlan({
@@ -812,9 +817,39 @@ export function validateEditionLayoutPlanForItems(
     }
   }
 
+  validateJumpTargetsHaveContinuationFrames(layoutPlan, label);
+
   return layoutPlan;
 }
 
+function validateJumpTargetsHaveContinuationFrames(layoutPlan: EditionLayoutPlan, label: string): void {
+  const continuationFlowKeysByPageNumber = new Map<number, Set<string>>();
+  for (const page of layoutPlan.pages) {
+    const flowKeys = new Set<string>();
+    for (const region of page.regions) {
+      for (const block of region.blocks) {
+        if (block.type === "articleFrame" && block.startCursor === "current") flowKeys.add(block.flowKey ?? block.itemId);
+      }
+    }
+    continuationFlowKeysByPageNumber.set(page.pageNumber, flowKeys);
+  }
+  for (const page of layoutPlan.pages) {
+    for (const region of page.regions) {
+      for (const block of region.blocks) {
+        if (block.type !== "articleFrame") continue;
+        const jumpTargetPage = block.cutPolicy?.jumpTargetPage;
+        if (!jumpTargetPage) continue;
+        const flowKey = block.flowKey ?? block.itemId;
+        if (!continuationFlowKeysByPageNumber.get(jumpTargetPage)?.has(flowKey)) {
+          throw new Error(
+            `${label}.pages[${page.pageNumber}].regions.${region.id}.${block.id} advertises page ${jumpTargetPage} but that page has no startCursor "current" frame for flow ${flowKey}`,
+          );
+        }
+      }
+    }
+  }
+}
+
 function validateBlock(
   block: LayoutBlockSpec,
   itemsBySlug: Map<string, PublicationItem>,
@@ -954,13 +989,6 @@ function getDefaultFrontItemOrder(itemIds: string[]): string[] {
   return [itemIds[1], itemIds[0], itemIds[2], ...itemIds.slice(3)];
 }
 
-function getDefaultCutPolicy(itemId: string): ArticleFrameBlockSpec["cutPolicy"] | undefined {
-  if (itemId === "agent-procedure-patterns") return { maxBodyLines: 22, jumpTargetPage: 2 };
-  if (itemId === "schools-reading-lab") return { maxBodyLines: 16, jumpTargetPage: 3 };
-  if (itemId === "market-hall") return { maxBodyLines: 14, jumpTargetPage: 3 };
-  return undefined;
-}
-
 function parseMaybeJson(value: unknown, label: string): unknown {
   if (typeof value !== "string") {
     if (value === undefined || value === null) throw new Error(`${label} is required`);

package/lib/layout-scenarios.ts

@@ -1,7 +1,7 @@
 import { type Article, type ArticleVideoAsset, articles, editionDate } from "./articles";
 import type { EditionContent, NewsDeskAppendix } from "./content-types";
 import { createEditionSectionPlan } from "./edition-sections";
-import { createDefaultEditionLayoutPlan, type EditionLayoutPlan } from "./layout-plan";
+import { createDefaultEditionLayoutPlan, type ArticleCutPolicy, type EditionLayoutPlan } from "./layout-plan";
 import { articleToPublicationItem, cloneArticle } from "./publication-items";
 import { PILOBOL_SAMPLE_SCENARIO_ID, createPilobolSampleEditionContent } from "./pilobol-sample";
 import { SITE_BRAND } from "./site-brand";
@@ -17,6 +17,16 @@ type RawLayoutScenario = Omit<LayoutScenario, "sections"> & {
   sections?: LayoutScenario["sections"];
 };
 
+const fixtureCutPoliciesByItemId: Record<string, ArticleCutPolicy> = {
+  "agent-procedure-patterns": { maxBodyLines: 22, jumpTargetPage: 2 },
+  "schools-reading-lab": { maxBodyLines: 16, jumpTargetPage: 3 },
+  "market-hall": { maxBodyLines: 14, jumpTargetPage: 3 },
+};
+
+export function createFixtureEditionLayoutPlan(itemIds: string[]): EditionLayoutPlan {
+  return createDefaultEditionLayoutPlan(itemIds, fixtureCutPoliciesByItemId);
+}
+
 const defaultScenarioSeed = getDefaultScenarioSeed();
 
 const rawLayoutScenarios: RawLayoutScenario[] = [
@@ -27,7 +37,7 @@ const rawLayoutScenarios: RawLayoutScenario[] = [
     editionDate: defaultScenarioSeed.editionDate,
     scenarioId: DEFAULT_LAYOUT_SCENARIO_ID,
     description: defaultScenarioSeed.description,
-    layoutPlan: createDefaultEditionLayoutPlan(defaultScenarioSeed.articles.map((article) => article.slug)),
+    layoutPlan: createFixtureEditionLayoutPlan(defaultScenarioSeed.articles.map((article) => article.slug)),
     items: cloneArticles(defaultScenarioSeed.articles).map(articleToPublicationItem),
     suppressNewsDeskAppendix: defaultScenarioSeed.suppressNewsDeskAppendix,
     editionVideo: defaultScenarioSeed.editionVideo,
@@ -40,7 +50,7 @@ const rawLayoutScenarios: RawLayoutScenario[] = [
     editionDate,
     scenarioId: "blank-edition-title",
     description: "A fixture edition with a blank title used to verify masthead fallback labeling.",
-    layoutPlan: createDefaultEditionLayoutPlan(articles.map((article) => article.slug)),
+    layoutPlan: createFixtureEditionLayoutPlan(articles.map((article) => article.slug)),
     items: cloneArticles(articles).map(articleToPublicationItem),
   },
   {
@@ -51,7 +61,7 @@ const rawLayoutScenarios: RawLayoutScenario[] = [
     scenarioId: "shared-blank-column-pressure",
     description:
       "Shorter shared continuation tails with images and pull quotes, used to prove that empty columns are repaired with solved furniture.",
-    layoutPlan: createDefaultEditionLayoutPlan(articles.map((article) => article.slug)),
+    layoutPlan: createFixtureEditionLayoutPlan(articles.map((article) => article.slug)),
     items: createSharedBlankColumnPressureArticles().map(articleToPublicationItem),
   },
   {
@@ -62,7 +72,7 @@ const rawLayoutScenarios: RawLayoutScenario[] = [
     scenarioId: "shared-continuation-no-pull-quotes",
     description:
       "The shared continuation page with editorial pull quotes removed, used to prove pull quotes are optional display furniture.",
-    layoutPlan: createDefaultEditionLayoutPlan(articles.map((article) => article.slug)),
+    layoutPlan: createFixtureEditionLayoutPlan(articles.map((article) => article.slug)),
     items: createNoPullQuoteArticles().map(articleToPublicationItem),
   },
   {
@@ -106,7 +116,7 @@ const rawLayoutScenarios: RawLayoutScenario[] = [
     scenarioId: "long-image-caption",
     description:
       "A continuation image with a long caption proves image furniture reserves enough rhythm rows for complete caption text.",
-    layoutPlan: createDefaultEditionLayoutPlan(articles.map((article) => article.slug)),
+    layoutPlan: createFixtureEditionLayoutPlan(articles.map((article) => article.slug)),
     items: createLongImageCaptionArticles().map(articleToPublicationItem),
   },
   {
@@ -116,7 +126,7 @@ const rawLayoutScenarios: RawLayoutScenario[] = [
     editionDate,
     scenarioId: "themed-ink-study",
     description: "A raster fixture verifies dark-mode image variant switching in solved newspaper image furniture.",
-    layoutPlan: createDefaultEditionLayoutPlan(articles.map((article) => article.slug)),
+    layoutPlan: createFixtureEditionLayoutPlan(articles.map((article) => article.slug)),
     items: createThemedInkStudyArticles().map(articleToPublicationItem),
   },
   {
@@ -377,7 +387,7 @@ function createHeightPolicyLayoutPlan({
   defaultRows?: number;
   blockShrinkToContent?: boolean;
 }): EditionLayoutPlan {
-  const plan = cloneLayoutPlan(createDefaultEditionLayoutPlan(articles.map((article) => article.slug)));
+  const plan = cloneLayoutPlan(createFixtureEditionLayoutPlan(articles.map((article) => article.slug)));
   const region = findPlanRegion(plan, "harbor-continuation");
   if (region) {
     if (regionShrinkToContent === undefined) {
@@ -472,7 +482,7 @@ function cloneArticles(source: Article[]): Article[] {
 }
 
 function createCompactChromeLayoutPlan(): EditionLayoutPlan {
-  const plan = cloneLayoutPlan(createDefaultEditionLayoutPlan(articles.map((article) => article.slug)));
+  const plan = cloneLayoutPlan(createFixtureEditionLayoutPlan(articles.map((article) => article.slug)));
   const frontPage = plan.pages.find((page) => page.pageNumber === 1);
   const frontBlocks = frontPage?.regions.flatMap((region) => region.blocks) ?? [];
   for (const block of frontBlocks) {
@@ -498,7 +508,7 @@ function createCompactChromeLayoutPlan(): EditionLayoutPlan {
 }
 
 function createFrontBodyDepthLayoutPlan(): EditionLayoutPlan {
-  const plan = cloneLayoutPlan(createDefaultEditionLayoutPlan(articles.map((article) => article.slug)));
+  const plan = cloneLayoutPlan(createFixtureEditionLayoutPlan(articles.map((article) => article.slug)));
   for (const blockId of ["front-agent-procedure-patterns", "front-schools-reading-lab", "front-market-hall"]) {
     const block = findPlanBlock(plan, blockId);
     if (block?.type !== "articleFrame") continue;
@@ -511,7 +521,7 @@ function createFrontBodyDepthLayoutPlan(): EditionLayoutPlan {
 }
 
 function createFurnitureSufficiencyLayoutPlan(): EditionLayoutPlan {
-  const plan = cloneLayoutPlan(createDefaultEditionLayoutPlan(articles.map((article) => article.slug)));
+  const plan = cloneLayoutPlan(createFixtureEditionLayoutPlan(articles.map((article) => article.slug)));
   const frontSchoolsBlock = findPlanBlock(plan, "front-schools-reading-lab");
   if (frontSchoolsBlock?.type === "articleFrame") {
     frontSchoolsBlock.cutPolicy = { maxBodyLines: 4, jumpTargetPage: 3 };

package/lib/layout-types.ts

@@ -0,0 +1,457 @@
+import { type LayoutCursor, type TextLine } from "./pretext-layout";
+import { type ArticleImageThemeVariants } from "./articles";
+import {
+  type ArticleFrameBlockSpec,
+  type EditorialPriorityId,
+  type HeadlineScaleId,
+  type LayoutBlockSpec,
+  type LayoutPageSpec,
+  type LayoutRegionSpec,
+  type ResponsivePlacementSpec,
+} from "./layout-plan";
+import { type ArticlePublicationItem, type PublicationItem } from "./publication-items";
+import { type VerticalRhythm } from "./blog-rhythm";
+
+export type SolvedTextLine = TextLine;
+
+export type SolvedFurniture = SolvedImageFurniture | SolvedPullQuoteFurniture | SolvedMediaClusterFurniture | SolvedAdFurniture;
+
+export type SolvedImageFurniture = {
+  kind: "image";
+  id: string;
+  assetId: string;
+  src: string;
+  themeVariants?: ArticleImageThemeVariants;
+  alt: string;
+  caption: string;
+  credit: string;
+  templateId: string;
+  columnStart: number;
+  columnSpan: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  imageHeight: number;
+  captionHeight: number;
+  captionFontSize: number;
+  captionLineHeight: number;
+  aspectRatio: number;
+  objectFit: "contain" | "cover";
+  objectPosition: string;
+  wrapsText: boolean;
+  preferredHeight: number;
+};
+
+export type SolvedPullQuoteFurniture = {
+  kind: "pullQuote";
+  id: string;
+  text: string;
+  templateId: string;
+  columnStart: number;
+  columnSpan: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  fontSize: number;
+  lineHeight: number;
+  wrapsText: boolean;
+};
+
+export type SolvedMediaClusterFurniture = {
+  kind: "mediaCluster";
+  id: string;
+  templateId: string;
+  images: SolvedImageFurniture[];
+  caption: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  wrapsText: false;
+};
+
+export type SolvedAdFurniture = {
+  kind: "ad";
+  id: string;
+  src?: string;
+  label: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  wrapsText: false;
+};
+
+export type SolvedChromeBox = {
+  id: string;
+  slot: "label" | "headline" | "deck" | "byline";
+  text: string;
+  columnStart: number;
+  columnSpan: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  fontSize: number;
+  lineHeight: number;
+  paintBuffer: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  ruleTopHeight?: number;
+  ruleBottomHeight?: number;
+  fontFamily: "serif" | "sans";
+  fontWeight?: number | string;
+  fontStyle?: "normal" | "italic";
+  textTransform?: "uppercase";
+};
+
+export type SolvedBlock = {
+  id: string;
+  type: LayoutBlockSpec["type"];
+  presetId?: string;
+  headlineScale?: HeadlineScaleId;
+  editorialPriority?: EditorialPriorityId;
+  item?: PublicationItem;
+  items?: PublicationItem[];
+  article?: ArticlePublicationItem;
+  pageNumber: number;
+  jumpTargetPage?: number;
+  jumpLabel?: string;
+  label?: string;
+  title?: string;
+  deck?: string;
+  byline?: string;
+  dateline?: string;
+  section?: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  span: number;
+  columnCount: number;
+  columns: TextLine[][];
+  chromeBoxes?: SolvedChromeBox[];
+  furniture: SolvedFurniture[];
+  textRange?: PlacedTextRange;
+  hasMore?: boolean;
+  front?: SolvedFrontStoryMetrics;
+  titleChrome?: ContinuationTitleMetrics;
+  titleHeight?: number;
+  bodyHeight?: number;
+  furnitureSufficiency?: FurnitureSufficiencyReport;
+};
+
+export type SolvedFrontStoryMetrics = {
+  rowHeight: number;
+  bodySlotHeight: number;
+  chromeHeight: number;
+  jumpReserveHeight: number;
+  chrome: StoryChromeMetrics;
+  gridPlacement?: SolvedFrontGridPlacement;
+  composition?: {
+    mode: FrontCompositionFlowMode;
+    bodyTop: number;
+    bodyHeight: number;
+    columnCount: number;
+    copyBandTop: number;
+    copyBandTops: number[];
+  };
+};
+
+export type SolvedFrontGridPlacement = {
+  columnStart: number;
+  columnSpan: number;
+  rowStart: number;
+  rowSpan: number;
+};
+
+export type SolvedRegion = {
+  id: string;
+  type: LayoutRegionSpec["type"];
+  role?: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rowHeights?: number[];
+  columnCount: number;
+  blocks: SolvedBlock[];
+};
+
+export type SolvedFrontFooterEntry = {
+  section: string;
+  articleSlug: string;
+  articleTitle: string;
+  blockId: string;
+  pageNumber: number;
+};
+
+export type SolvedFrontFooterUtilityEntry =
+  | {
+      id: "archive";
+      label: string;
+      href: string;
+      disabled: false;
+    }
+  | {
+      id: "newsDesk";
+      label: string;
+      href: string;
+      disabled: false;
+    }
+  | {
+      id: "settings";
+      label: string;
+      href: string;
+      disabled: false;
+    }
+  | {
+      id: "login";
+      label: string;
+      disabled: true;
+    };
+
+export type SolvedFrontFooter = {
+  rowHeight: number;
+  marginTop: number;
+  height: number;
+  sectionRows: number;
+  sectionColumns: number;
+  entries: SolvedFrontFooterEntry[];
+  utilityEntries: SolvedFrontFooterUtilityEntry[];
+};
+
+export type SolvedPage = {
+  id: string;
+  pageNumber: number;
+  presetId: LayoutPageSpec["presetId"];
+  kind: string;
+  height: number;
+  columnCount: number;
+  regions: SolvedRegion[];
+  frontFooter?: SolvedFrontFooter;
+};
+
+export type NewspaperLayout = {
+  columnCount: number;
+  contentWidth: number;
+  gap: number;
+  rowGap: number;
+  rhythm: VerticalRhythm;
+  pageHeight: number;
+  frontPageHeight: number;
+  pageHeights: Record<number, number>;
+  pageChrome: PageChromeMetrics;
+  pages: SolvedPage[];
+  textRanges: PlacedTextRange[];
+};
+
+export type PageChromeMetrics = {
+  pagePaddingTop: number;
+  pagePaddingX: number;
+  pagePaddingBottom: number;
+  mastheadHeight: number;
+  mastheadKickerLineHeight: number;
+  mastheadTitleFontSize: number;
+  mastheadTitleLineHeight: number;
+  mastheadTitleMarginTop: number;
+  mastheadTitleMarginBottom: number;
+  mastheadTitleOpticalShift: number;
+  mastheadMetaLineHeight: number;
+  mastheadMetaGap: number;
+  mastheadMetaPaddingTop: number;
+  frontGridMarginTop: number;
+  insideHeaderHeight: number;
+  continuedTitleHeight: number;
+  continuedTitleChromeHeight: number;
+  continuedTitleFontSize: number;
+  continuedTitleLineHeight: number;
+  continuationSectionSeparatorHeight: number;
+};
+
+export type ChromeTextBoxMetrics = {
+  fontSize: number;
+  lineHeight: number;
+  paintHeight: number;
+  paintBuffer: number;
+  contentHeight: number;
+  paddingTop: number;
+  paddingBottom: number;
+  ruleTopHeight: number;
+  ruleBottomHeight: number;
+  height: number;
+  lineCount: number;
+  marginBefore: number;
+  marginAfter: number;
+  totalHeight: number;
+};
+
+export type StoryChromeMetrics = {
+  borderTopHeight: number;
+  paddingTop: number;
+  mediaPreludeHeight: number;
+  mediaPreludeMarginBottom: number;
+  labelFontSize: number;
+  labelLineHeight: number;
+  labelPaintHeight: number;
+  labelPaintBuffer: number;
+  labelHeight: number;
+  headlineFontSize: number;
+  headlineLineHeight: number;
+  headlinePaintHeight: number;
+  headlinePaintBuffer: number;
+  headlineHeight: number;
+  headlineLineCount: number;
+  headlineMarginTop: number;
+  headlineMarginBottom: number;
+  deckFontSize: number;
+  deckLineHeight: number;
+  deckPaintHeight: number;
+  deckPaintBuffer: number;
+  deckPaddingTop: number;
+  deckPaddingBottom: number;
+  deckRuleTopHeight: number;
+  deckRuleBottomHeight: number;
+  deckHeight: number;
+  deckLineCount: number;
+  deckMarginBottom: number;
+  bylineFontSize: number;
+  bylineLineHeight: number;
+  bylinePaintHeight: number;
+  bylinePaintBuffer: number;
+  bylinePaddingTop: number;
+  bylinePaddingBottom: number;
+  bylineHeight: number;
+  bylineLineCount: number;
+  bylineMarginBottom: number;
+  measureChromeHeight: number;
+  jumpFontSize: number;
+  jumpLineHeight: number;
+  jumpPaintHeight: number;
+  jumpPaintBuffer: number;
+  jumpHeight: number;
+  jumpPaddingTop: number;
+  jumpPaddingBottom: number;
+  jumpBorderTopHeight: number;
+};
+
+export type ContinuationTitleMetrics = {
+  label: ChromeTextBoxMetrics;
+  heading: ChromeTextBoxMetrics;
+  chromeHeight: number;
+  totalHeight: number;
+};
+
+export type FrontStoryRole = "feature" | "rail" | "standard";
+
+export type ChromeTextStyle = {
+  fontSize: number;
+  fontFamily: string;
+  fontWeight?: number | string;
+  fontStyle?: "normal" | "italic";
+  lineHeightEm: number;
+  paintHeightEm: number;
+  marginBeforeEm?: number;
+  marginAfterEm?: number;
+  minHeightEm?: number;
+};
+
+export type ChromeBoxTreatment = {
+  paddingTop: number;
+  paddingBottom: number;
+  ruleTopHeight?: number;
+  ruleBottomHeight?: number;
+};
+
+export type PlacedTextRange = {
+  articleId: string;
+  pageId: string;
+  blockId: string;
+  startCursor: LayoutCursor;
+  endCursor: LayoutCursor;
+  exhausted: boolean;
+};
+
+export type ArticleFlow = {
+  article: ArticlePublicationItem;
+  currentCursor: LayoutCursor;
+  placedRanges: PlacedTextRange[];
+  usedImageAssetIds: Set<string>;
+};
+
+export type LayoutConfig = {
+  columnCount: number;
+  contentWidth: number;
+  gap: number;
+  rowGap: number;
+  rhythm: VerticalRhythm;
+  pageChrome: PageChromeMetrics;
+  lineHeight: number;
+  linePaintHeight: number;
+  bodyFontSize: number;
+  bodyFont: string;
+  frontRows: FrontRow[];
+  continuationHeight: number;
+};
+
+export type FrontRow = {
+  startIndex: number;
+  endIndex: number;
+  height: number;
+};
+
+export type FrontArticlePlacement = {
+  block: ArticleFrameBlockSpec;
+  originalIndex: number;
+  solveIndex: number;
+  gridPlacement?: SolvedFrontGridPlacement;
+  rowHeight?: number;
+};
+
+export type FrontArticleSolveOptions = {
+  enforcePlacementHeight?: boolean;
+};
+
+export type FrontCompositionFlowMode = "offsetBody" | "integrated" | "titleStackedMedia" | "stackedMedia";
+
+export type ArticleFrameCandidate = {
+  block: SolvedBlock;
+  range: PlacedTextRange;
+  score: number;
+  whitespace: number;
+  furnitureSufficiency?: FurnitureSufficiencyReport;
+};
+
+export type FurnitureSufficiencyReport = {
+  accepted: boolean;
+  reason?: string;
+  visibleRows: number;
+  furnitureRows: number;
+};
+
+export type MediaVariant = {
+  id: string;
+  placement: ResponsivePlacementSpec | null;
+  assetRole?: string;
+  columnStart: number;
+  columnSpan: number;
+  fallbackPenalty: number;
+};
+
+export type PlacementVariant = {
+  id: string;
+  placement: ResponsivePlacementSpec;
+  columnStart: number;
+  columnSpan: number;
+  fallbackPenalty: number;
+};
+
+export type PullQuoteVariant = {
+  id: string;
+  placement: ResponsivePlacementSpec | null;
+  columnStart: number;
+  columnSpan: number;
+  fallbackPenalty: number;
+};