@anthusai/papyrus 1.0.0-next.16 → 1.0.0-next.18

package/infra/site-config.js

@@ -3,6 +3,7 @@ const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
 const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
@@ -11,7 +12,7 @@ const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}
 const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH"];
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH"];
 const LOCAL_DEVELOPMENT_ORIGIN = "http://localhost:3001/";
 function fail(field, problem) {
     throw new Error(`site.json: ${field} ${problem}`);
@@ -53,9 +54,17 @@ function rejectUnknownKeys(record, allowed, field) {
 export function isStagingEnabled(config) {
     return config.cms.staging !== false;
 }
+export function resolveCmsHostName(config) {
+    if (!config.cms.domainName)
+        return undefined;
+    return config.cms.domainPrefix ? `${config.cms.domainPrefix}.${config.cms.domainName}` : config.cms.domainName;
+}
 export function resolveStagingDomainName(config) {
     if (!isStagingEnabled(config))
         return undefined;
+    if (config.cms.domainPrefix) {
+        return config.cms.stagingDomainPrefix ? `${config.cms.stagingDomainPrefix}.${config.cms.domainName}` : undefined;
+    }
     if (config.cms.stagingDomainName)
         return config.cms.stagingDomainName;
     if (!config.cms.domainName)
@@ -84,7 +93,7 @@ export function parseSiteConfig(raw) {
     const papyrusVersion = requireString(record.papyrusVersion, "papyrusVersion", PAPYRUS_VERSION_PATTERN, "exact version such as 1.0.0 or 1.0.0-next.1");
     const storagePreviewPrefix = optionalString(record.storagePreviewPrefix, "storagePreviewPrefix", /^[A-Za-z0-9._-]+\/$/, "must end with /");
     const cmsRecord = requireObject(record.cms, "cms");
-    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName"], "cms");
+    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix"], "cms");
     const buildComputeType = cmsRecord.buildComputeType;
     if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
         fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -92,14 +101,20 @@ export function parseSiteConfig(raw) {
     if (cmsRecord.staging !== undefined && typeof cmsRecord.staging !== "boolean") {
         fail("cms.staging", `must be a boolean, got ${JSON.stringify(cmsRecord.staging)}`);
     }
+    if (cmsRecord.applyCognitoDomainPrefix !== undefined && typeof cmsRecord.applyCognitoDomainPrefix !== "boolean") {
+        fail("cms.applyCognitoDomainPrefix", `must be a boolean, got ${JSON.stringify(cmsRecord.applyCognitoDomainPrefix)}`);
+    }
     const cms = {
         appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
         domainName: optionalString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
+        domainPrefix: optionalString(cmsRecord.domainPrefix, "cms.domainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
         staging: cmsRecord.staging,
         cognitoDomainPrefix: requireString(cmsRecord.cognitoDomainPrefix, "cms.cognitoDomainPrefix", COGNITO_DOMAIN_PREFIX_PATTERN, "lowercase letters, digits and hyphens; globally unique per region"),
+        applyCognitoDomainPrefix: cmsRecord.applyCognitoDomainPrefix,
         buildComputeType: buildComputeType,
         environment: requireStringRecord(cmsRecord.environment, "cms.environment"),
         stagingDomainName: optionalString(cmsRecord.stagingDomainName, "cms.stagingDomainName", HOST_NAME_PATTERN, "host name"),
+        stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
     };
     const reservedWord = COGNITO_RESERVED_WORDS.find((word) => cms.cognitoDomainPrefix.includes(word));
     if (reservedWord) {
@@ -116,6 +131,24 @@ export function parseSiteConfig(raw) {
     if (cms.stagingDomainName && !cms.domainName) {
         fail("cms.stagingDomainName", "requires cms.domainName");
     }
+    if (cms.domainPrefix && !cms.domainName) {
+        fail("cms.domainPrefix", "requires cms.domainName (the root domain)");
+    }
+    if (cms.stagingDomainPrefix && !cms.domainPrefix) {
+        fail("cms.stagingDomainPrefix", "requires cms.domainPrefix");
+    }
+    if (cms.domainPrefix && cms.stagingDomainName) {
+        fail("cms.stagingDomainName", "must not be set with cms.domainPrefix: use cms.stagingDomainPrefix");
+    }
+    if (cms.staging === false && cms.stagingDomainPrefix) {
+        fail("cms.stagingDomainPrefix", "must not be set when cms.staging is false");
+    }
+    if (cms.domainPrefix && cms.staging !== false && !cms.stagingDomainPrefix) {
+        fail("cms.stagingDomainPrefix", "is required when cms.domainPrefix is set and staging is enabled: the staging host is never derived under a shared root domain");
+    }
+    if (cms.domainPrefix && cms.stagingDomainPrefix === cms.domainPrefix) {
+        fail("cms.stagingDomainPrefix", "must differ from cms.domainPrefix");
+    }
     let reader;
     if (record.reader !== undefined) {
         if (frontend !== "markus-static")
@@ -186,7 +219,7 @@ export function parseSiteConfig(raw) {
     const redirectUrls = redirectValue.split(",").map((url) => url.trim());
     const stagingDomainName = resolveStagingDomainName(config);
     const requiredOrigins = [
-        ...(cms.domainName ? [`https://${cms.domainName}/`] : []),
+        ...(resolveCmsHostName(config) ? [`https://${resolveCmsHostName(config)}/`] : []),
         ...(stagingDomainName ? [`https://${stagingDomainName}/`] : []),
         LOCAL_DEVELOPMENT_ORIGIN,
     ];

package/infra/site-config.ts

@@ -8,11 +8,14 @@ export type AmplifyAppShellSiteConfig = {
   cms: {
     appName?: string;
     domainName?: string;
+    domainPrefix?: string;
     staging?: boolean;
     cognitoDomainPrefix: string;
+    applyCognitoDomainPrefix?: boolean;
     buildComputeType?: "STANDARD" | "STANDARD_8GB";
     environment: Record<string, string>;
     stagingDomainName?: string;
+    stagingDomainPrefix?: string;
   };
   reader?: {
     appName?: string;
@@ -38,6 +41,7 @@ const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
 const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
@@ -46,7 +50,7 @@ const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}
 const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const COGNITO_DOMAIN_PREFIX_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const COGNITO_RESERVED_WORDS = ["aws", "amazon", "cognito"];
-const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH"];
+const TEMPLATE_MANAGED_ENVIRONMENT_KEYS = ["PAPYRUS_COGNITO_DOMAIN_PREFIX", "PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX", "PAPYRUS_DISABLE_GOOGLE_OAUTH"];
 const LOCAL_DEVELOPMENT_ORIGIN = "http://localhost:3001/";
 
 function fail(field: string, problem: string): never {
@@ -94,8 +98,16 @@ export function isStagingEnabled(config: Pick<AmplifyAppShellSiteConfig, "cms">)
   return config.cms.staging !== false;
 }
 
+export function resolveCmsHostName(config: Pick<AmplifyAppShellSiteConfig, "cms">): string | undefined {
+  if (!config.cms.domainName) return undefined;
+  return config.cms.domainPrefix ? `${config.cms.domainPrefix}.${config.cms.domainName}` : config.cms.domainName;
+}
+
 export function resolveStagingDomainName(config: Pick<AmplifyAppShellSiteConfig, "cms">): string | undefined {
   if (!isStagingEnabled(config)) return undefined;
+  if (config.cms.domainPrefix) {
+    return config.cms.stagingDomainPrefix ? `${config.cms.stagingDomainPrefix}.${config.cms.domainName}` : undefined;
+  }
   if (config.cms.stagingDomainName) return config.cms.stagingDomainName;
   if (!config.cms.domainName) return undefined;
   const [, ...rest] = config.cms.domainName.split(".");
@@ -131,7 +143,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   const storagePreviewPrefix = optionalString(record.storagePreviewPrefix, "storagePreviewPrefix", /^[A-Za-z0-9._-]+\/$/, "must end with /");
 
   const cmsRecord = requireObject(record.cms, "cms");
-  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName"], "cms");
+  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "staging", "cognitoDomainPrefix", "applyCognitoDomainPrefix", "buildComputeType", "environment", "stagingDomainName", "domainPrefix", "stagingDomainPrefix"], "cms");
   const buildComputeType = cmsRecord.buildComputeType;
   if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
     fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
@@ -139,9 +151,13 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   if (cmsRecord.staging !== undefined && typeof cmsRecord.staging !== "boolean") {
     fail("cms.staging", `must be a boolean, got ${JSON.stringify(cmsRecord.staging)}`);
   }
+  if (cmsRecord.applyCognitoDomainPrefix !== undefined && typeof cmsRecord.applyCognitoDomainPrefix !== "boolean") {
+    fail("cms.applyCognitoDomainPrefix", `must be a boolean, got ${JSON.stringify(cmsRecord.applyCognitoDomainPrefix)}`);
+  }
   const cms: AmplifyAppShellSiteConfig["cms"] = {
     appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
     domainName: optionalString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
+    domainPrefix: optionalString(cmsRecord.domainPrefix, "cms.domainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
     staging: cmsRecord.staging as boolean | undefined,
     cognitoDomainPrefix: requireString(
       cmsRecord.cognitoDomainPrefix,
@@ -149,9 +165,11 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
       COGNITO_DOMAIN_PREFIX_PATTERN,
       "lowercase letters, digits and hyphens; globally unique per region",
     ),
+    applyCognitoDomainPrefix: cmsRecord.applyCognitoDomainPrefix as boolean | undefined,
     buildComputeType: buildComputeType as "STANDARD" | "STANDARD_8GB" | undefined,
     environment: requireStringRecord(cmsRecord.environment, "cms.environment"),
     stagingDomainName: optionalString(cmsRecord.stagingDomainName, "cms.stagingDomainName", HOST_NAME_PATTERN, "host name"),
+    stagingDomainPrefix: optionalString(cmsRecord.stagingDomainPrefix, "cms.stagingDomainPrefix", DOMAIN_PREFIX_PATTERN, "single DNS label"),
   };
 
   const reservedWord = COGNITO_RESERVED_WORDS.find((word) => cms.cognitoDomainPrefix.includes(word));
@@ -170,6 +188,24 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   if (cms.stagingDomainName && !cms.domainName) {
     fail("cms.stagingDomainName", "requires cms.domainName");
   }
+  if (cms.domainPrefix && !cms.domainName) {
+    fail("cms.domainPrefix", "requires cms.domainName (the root domain)");
+  }
+  if (cms.stagingDomainPrefix && !cms.domainPrefix) {
+    fail("cms.stagingDomainPrefix", "requires cms.domainPrefix");
+  }
+  if (cms.domainPrefix && cms.stagingDomainName) {
+    fail("cms.stagingDomainName", "must not be set with cms.domainPrefix: use cms.stagingDomainPrefix");
+  }
+  if (cms.staging === false && cms.stagingDomainPrefix) {
+    fail("cms.stagingDomainPrefix", "must not be set when cms.staging is false");
+  }
+  if (cms.domainPrefix && cms.staging !== false && !cms.stagingDomainPrefix) {
+    fail("cms.stagingDomainPrefix", "is required when cms.domainPrefix is set and staging is enabled: the staging host is never derived under a shared root domain");
+  }
+  if (cms.domainPrefix && cms.stagingDomainPrefix === cms.domainPrefix) {
+    fail("cms.stagingDomainPrefix", "must differ from cms.domainPrefix");
+  }
 
   let reader: AmplifyAppShellSiteConfig["reader"];
   if (record.reader !== undefined) {
@@ -241,7 +277,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   const redirectUrls = redirectValue.split(",").map((url) => url.trim());
   const stagingDomainName = resolveStagingDomainName(config);
   const requiredOrigins = [
-    ...(cms.domainName ? [`https://${cms.domainName}/`] : []),
+    ...(resolveCmsHostName(config) ? [`https://${resolveCmsHostName(config)}/`] : []),
     ...(stagingDomainName ? [`https://${stagingDomainName}/`] : []),
     LOCAL_DEVELOPMENT_ORIGIN,
   ];

package/lib/blog-feature-solver.ts

@@ -0,0 +1,459 @@
+import type { ArticleImageAsset } from "./articles";
+import type { PublicationItem } from "./publication-items";
+import {
+  createDefaultBlogVerticalRhythm,
+  getMeasuredTextHeight,
+  reserveRhythmRows,
+  snapDownToRhythm,
+  snapPreferredHeightToRhythm,
+  snapPreservedImageHeightToRhythm,
+  type BlogTextStyle,
+  type VerticalRhythm,
+} from "./blog-rhythm";
+import { layoutAllTextLines, layoutTextLines, prepareWithSegments, type TextLine, type TextObstacle } from "./pretext-layout";
+
+export type FeaturedLayoutMode = "obstacle" | "float" | "stacked";
+
+export type SolvedFeaturedItem = {
+  mode: FeaturedLayoutMode;
+  textLines: TextLine[];
+  imageHeight: number;
+  imageWidth: number;
+  /** Image frame + caption/credit block reserved below the frame. */
+  mediaHeight: number;
+  captionHeight: number;
+  copyWidth: number;
+  textFrameHeight: number;
+  hasMore: boolean;
+  gap: number;
+};
+
+export type SolvedFeaturedFloatGeometry = {
+  mode: "float";
+  imageHeight: number;
+  imageWidth: number;
+  mediaHeight: number;
+  captionHeight: number;
+  copyWidth: number;
+  gap: number;
+};
+
+export type SolveFeaturedItemInput = {
+  text: string;
+  containerWidth: number;
+  viewportWidth: number;
+  rhythm?: VerticalRhythm;
+  textStyle: BlogTextStyle;
+  imageAsset: ArticleImageAsset;
+  itemIndex?: number;
+};
+
+export type SolveFeaturedFloatGeometryInput = {
+  containerWidth: number;
+  viewportWidth: number;
+  rhythm?: VerticalRhythm;
+  imageAsset: Pick<ArticleImageAsset, "layout" | "caption" | "credit">;
+  itemIndex?: number;
+  /** Fraction of container width for the image. Defaults to the edition-index teaser ratio. */
+  imageWidthRatio?: number;
+  /** Fraction of viewport width used as a hard image-width cap. Defaults to 1/3. */
+  viewportImageCapRatio?: number;
+  /** Absolute float width cap in rhythm rows. Stops percentage sizing from outgrowing the rail. */
+  maxWidthRows?: number;
+};
+
+const FLOAT_IMAGE_WIDTH_RATIO = 0.32;
+/** Article pages use a larger float so the pictogram reads as a feature, not a teaser. */
+const ARTICLE_FLOAT_IMAGE_WIDTH_RATIO = 0.48;
+const ARTICLE_VIEWPORT_IMAGE_CAP_RATIO = 0.5;
+/** Edition-index floats track the pictogram maxHeight band (~440px at 16px rows). */
+const FLOAT_IMAGE_MAX_WIDTH_ROWS = 27;
+/** Article floats read larger than teasers but must not keep growing on wide rails. */
+const ARTICLE_FLOAT_IMAGE_MAX_WIDTH_ROWS = 24;
+const FLOAT_IMAGE_MIN_PHONE_ROWS = 6;
+const FLOAT_IMAGE_MIN_DESKTOP_ROWS = 8;
+const FLOAT_COPY_MIN_PHONE_ROWS = 11;
+const FLOAT_COPY_MIN_DESKTOP_ROWS = 14;
+const LEAD_GAP_ROWS = 2;
+const LEAD_GAP_ROWS_NARROW = 1;
+const DEFAULT_GAP_ROWS = 4;
+
+export function getFeaturedLayoutMode(viewportWidth: number, hasImage: boolean): FeaturedLayoutMode {
+  if (!hasImage) return "stacked";
+  return "float";
+}
+
+export function solveFeaturedItem(input: SolveFeaturedItemInput): SolvedFeaturedItem {
+  const rhythm = input.rhythm ?? createDefaultBlogVerticalRhythm();
+  const gap = getFeaturedLayoutGap(input.viewportWidth, input.itemIndex, rhythm);
+  const mode = getFeaturedLayoutMode(input.viewportWidth, true);
+  const prepared = prepareWithSegments(input.text, `${input.textStyle.fontSize}px ${input.textStyle.fontFamily}`, {
+    whiteSpace: "pre-wrap",
+  });
+  const aspectRatio = getImageAspectRatio(input.imageAsset);
+
+  if (mode === "obstacle") {
+    return solveObstacleFeaturedItem({
+      prepared,
+      containerWidth: input.containerWidth,
+      viewportWidth: input.viewportWidth,
+      rhythm,
+      textStyle: input.textStyle,
+      aspectRatio,
+      gap,
+      imageAsset: input.imageAsset,
+    });
+  }
+
+  if (mode === "float") {
+    return solveFloatFeaturedItem({
+      prepared,
+      containerWidth: input.containerWidth,
+      viewportWidth: input.viewportWidth,
+      rhythm,
+      textStyle: input.textStyle,
+      aspectRatio,
+      gap,
+      imageAsset: input.imageAsset,
+    });
+  }
+
+  const lines = layoutAllTextLines({
+    prepared,
+    maxWidth: input.containerWidth,
+    ...input.textStyle,
+  });
+  const imageWidth = snapDownToRhythm(Math.round(input.containerWidth), rhythm);
+  const imageHeight = snapImageHeight(imageWidth / aspectRatio, rhythm, input.imageAsset.layout);
+  const captionHeight = getFeatureCaptionHeight(input.imageAsset, imageWidth, rhythm);
+  return {
+    mode,
+    textLines: lines,
+    imageHeight,
+    imageWidth,
+    captionHeight,
+    mediaHeight: imageHeight + captionHeight,
+    copyWidth: input.containerWidth,
+    textFrameHeight: reserveRhythmRows(getMeasuredTextHeight(lines), rhythm),
+    hasMore: false,
+    gap,
+  };
+}
+
+type PreparedSolveInput = {
+  prepared: ReturnType<typeof prepareWithSegments>;
+  containerWidth: number;
+  viewportWidth: number;
+  rhythm: VerticalRhythm;
+  textStyle: BlogTextStyle;
+  aspectRatio: number;
+  gap: number;
+  imageAsset: ArticleImageAsset;
+};
+
+function solveObstacleFeaturedItem(input: PreparedSolveInput): SolvedFeaturedItem {
+  const maxImageWidth = getFloatImageWidth(input);
+  let best: {
+    score: number;
+    textLines: TextLine[];
+    imageHeight: number;
+    imageWidth: number;
+    captionHeight: number;
+    mediaHeight: number;
+    copyWidth: number;
+    textFrameHeight: number;
+    hasMore: boolean;
+  } | null = null;
+
+  for (const imageWidth of getObstacleImageWidths(maxImageWidth, input.rhythm)) {
+    const copyWidth = Math.max(
+      getFloatCopyMinimum(input.viewportWidth, input.rhythm),
+      input.containerWidth - imageWidth - input.gap,
+    );
+    const imageHeight = snapImageHeight(imageWidth / input.aspectRatio, input.rhythm, input.imageAsset.layout);
+    const captionHeight = getFeatureCaptionHeight(input.imageAsset, imageWidth, input.rhythm);
+    const mediaHeight = imageHeight + captionHeight;
+    const obstacle: TextObstacle = {
+      x: Math.max(0, copyWidth - imageWidth),
+      y: 0,
+      width: imageWidth,
+      height: mediaHeight,
+    };
+
+    let candidateHeight = mediaHeight;
+    let result = layoutTextLines({
+      prepared: input.prepared,
+      cursor: { segmentIndex: 0, graphemeIndex: 0 },
+      maxHeight: candidateHeight,
+      maxWidth: copyWidth,
+      lineHeight: input.textStyle.lineHeight,
+      linePaintHeight: input.textStyle.linePaintHeight,
+      fontSize: input.textStyle.fontSize,
+      fontFamily: input.textStyle.fontFamily,
+      obstacles: [obstacle],
+    });
+
+    const textBottom = getMeasuredTextHeight(result.lines);
+    if (textBottom > 0 && textBottom < candidateHeight) {
+      candidateHeight = reserveRhythmRows(textBottom, input.rhythm);
+      obstacle.height = candidateHeight;
+      result = layoutTextLines({
+        prepared: input.prepared,
+        cursor: { segmentIndex: 0, graphemeIndex: 0 },
+        maxHeight: candidateHeight,
+        maxWidth: copyWidth,
+        lineHeight: input.textStyle.lineHeight,
+        linePaintHeight: input.textStyle.linePaintHeight,
+        fontSize: input.textStyle.fontSize,
+        fontFamily: input.textStyle.fontFamily,
+        obstacles: [obstacle],
+      });
+    }
+
+    const whitespace = Math.max(0, candidateHeight - getMeasuredTextHeight(result.lines));
+    const score = 50_000 - whitespace * 1.4 - Math.abs(candidateHeight - mediaHeight) * 0.35 - Math.abs(maxImageWidth - imageWidth) * 0.2;
+    const candidate = {
+      score,
+      textLines: result.lines,
+      imageHeight: Math.min(imageHeight, candidateHeight),
+      imageWidth,
+      captionHeight,
+      mediaHeight: candidateHeight,
+      copyWidth,
+      textFrameHeight: reserveRhythmRows(getMeasuredTextHeight(result.lines), input.rhythm),
+      hasMore: result.hasMore,
+    };
+    if (!best || candidate.score > best.score) best = candidate;
+  }
+
+  const fallbackImageHeight = input.rhythm.rowHeight * 6;
+  return {
+    mode: "obstacle",
+    textLines: best?.textLines ?? [],
+    imageHeight: best?.imageHeight ?? fallbackImageHeight,
+    imageWidth: best?.imageWidth ?? maxImageWidth,
+    captionHeight: best?.captionHeight ?? 0,
+    mediaHeight: best?.mediaHeight ?? fallbackImageHeight,
+    copyWidth: best?.copyWidth ?? input.containerWidth,
+    textFrameHeight: best?.textFrameHeight ?? 0,
+    hasMore: best?.hasMore ?? false,
+    gap: input.gap,
+  };
+}
+
+function solveFloatFeaturedItem(input: PreparedSolveInput): SolvedFeaturedItem {
+  const geometry = computeFloatGeometry({
+    containerWidth: input.containerWidth,
+    viewportWidth: input.viewportWidth,
+    rhythm: input.rhythm,
+    gap: input.gap,
+    aspectRatio: input.aspectRatio,
+    imageAsset: input.imageAsset,
+  });
+  // Full-width frame with the image+caption as a top-right obstacle so excerpt
+  // lines shorten beside the media block and resume full width below it.
+  const frameWidth = input.containerWidth;
+  const obstacle: TextObstacle = {
+    x: Math.max(0, frameWidth - geometry.imageWidth - geometry.gap),
+    y: 0,
+    width: geometry.imageWidth + geometry.gap,
+    height: geometry.mediaHeight,
+  };
+  const lines = layoutAllTextLines({
+    prepared: input.prepared,
+    maxWidth: frameWidth,
+    lineHeight: input.textStyle.lineHeight,
+    linePaintHeight: input.textStyle.linePaintHeight,
+    fontSize: input.textStyle.fontSize,
+    fontFamily: input.textStyle.fontFamily,
+    obstacles: [obstacle],
+  });
+
+  return {
+    mode: "float",
+    textLines: lines,
+    imageHeight: geometry.imageHeight,
+    imageWidth: geometry.imageWidth,
+    captionHeight: geometry.captionHeight,
+    mediaHeight: geometry.mediaHeight,
+    copyWidth: frameWidth,
+    textFrameHeight: reserveRhythmRows(getMeasuredTextHeight(lines), input.rhythm),
+    hasMore: false,
+    gap: geometry.gap,
+  };
+}
+
+/**
+ * Geometry-only float solve for article pages (and any consumer that renders
+ * flowing body copy rather than Pretext-measured excerpt lines). Shares the
+ * same width/height/gap math as the edition-index lead float.
+ */
+export function solveFeaturedFloatGeometry(input: SolveFeaturedFloatGeometryInput): SolvedFeaturedFloatGeometry {
+  const rhythm = input.rhythm ?? createDefaultBlogVerticalRhythm();
+  const gap = getFeaturedLayoutGap(input.viewportWidth, input.itemIndex, rhythm);
+  return {
+    mode: "float",
+    ...computeFloatGeometry({
+      containerWidth: input.containerWidth,
+      viewportWidth: input.viewportWidth,
+      rhythm,
+      gap,
+      aspectRatio: getImageAspectRatio(input.imageAsset),
+      imageAsset: input.imageAsset,
+      // Article pages default larger than edition teasers; callers can override.
+      imageWidthRatio: input.imageWidthRatio ?? ARTICLE_FLOAT_IMAGE_WIDTH_RATIO,
+      viewportImageCapRatio: input.viewportImageCapRatio ?? ARTICLE_VIEWPORT_IMAGE_CAP_RATIO,
+      maxWidthRows: input.maxWidthRows ?? ARTICLE_FLOAT_IMAGE_MAX_WIDTH_ROWS,
+    }),
+  };
+}
+
+type FloatGeometryInput = {
+  containerWidth: number;
+  viewportWidth: number;
+  rhythm: VerticalRhythm;
+  gap: number;
+  aspectRatio: number;
+  imageAsset: Pick<ArticleImageAsset, "caption" | "credit" | "layout">;
+  imageWidthRatio?: number;
+  viewportImageCapRatio?: number;
+  maxWidthRows?: number;
+};
+
+function computeFloatGeometry(input: FloatGeometryInput): Omit<SolvedFeaturedFloatGeometry, "mode"> {
+  let imageWidth = getFloatImageWidth(input);
+  // Keep the frame proportional when layout.maxHeight would otherwise clip a
+  // wide float down to the minimum height (snapPreferredHeightToRhythm falls
+  // back to min when natural height exceeds max).
+  const maxHeight = input.imageAsset.layout?.maxHeight ?? input.rhythm.rowHeight * 36;
+  const widthFromMaxHeight = snapDownToRhythm(maxHeight * input.aspectRatio, input.rhythm);
+  if (widthFromMaxHeight > 0) {
+    imageWidth = Math.min(imageWidth, widthFromMaxHeight);
+  }
+  const absoluteMaxWidth = rhythmLengthRows(input.maxWidthRows ?? FLOAT_IMAGE_MAX_WIDTH_ROWS, input.rhythm);
+  imageWidth = Math.min(imageWidth, absoluteMaxWidth);
+  const copyWidth = Math.max(
+    getFloatCopyMinimum(input.viewportWidth, input.rhythm),
+    input.containerWidth - imageWidth - input.gap,
+  );
+  const imageHeight = snapImageHeight(imageWidth / input.aspectRatio, input.rhythm, input.imageAsset.layout);
+  const captionHeight = getFeatureCaptionHeight(input.imageAsset, imageWidth, input.rhythm);
+  return {
+    imageHeight,
+    imageWidth,
+    captionHeight,
+    mediaHeight: imageHeight + captionHeight,
+    copyWidth,
+    gap: input.gap,
+  };
+}
+
+/** Matches the blog figcaption: meta size, one-row line box, rhythm-unit margin-top. */
+const FEATURE_CAPTION_FONT_SIZE = 12;
+
+function getFeatureCaptionHeight(
+  asset: Pick<ArticleImageAsset, "caption" | "credit">,
+  imageWidth: number,
+  rhythm: VerticalRhythm,
+): number {
+  const caption = (asset.caption ?? asset.credit ?? "").trim();
+  if (!caption) return 0;
+  const fontFamily = 'Georgia, "Times New Roman", serif';
+  const prepared = prepareWithSegments(caption, `${FEATURE_CAPTION_FONT_SIZE}px ${fontFamily}`, {
+    whiteSpace: "pre-wrap",
+  });
+  const lines = layoutAllTextLines({
+    prepared,
+    maxWidth: Math.max(1, imageWidth),
+    lineHeight: rhythm.rowHeight,
+    linePaintHeight: rhythm.rowHeight,
+    fontSize: FEATURE_CAPTION_FONT_SIZE,
+    fontFamily,
+  });
+  const textHeight = Math.max(rhythm.rowHeight, getMeasuredTextHeight(lines));
+  // Brand CSS: figcaption margin-top is one rhythm unit, a quarter of a row.
+  const marginTop = rhythm.rowHeight / 4;
+  return reserveRhythmRows(marginTop + textHeight, rhythm);
+}
+
+function getFeaturedLayoutGap(viewportWidth: number, itemIndex: number | undefined, rhythm: VerticalRhythm): number {
+  if (itemIndex === 0) {
+    return rhythmLengthRows(viewportWidth <= 600 ? LEAD_GAP_ROWS_NARROW : LEAD_GAP_ROWS, rhythm);
+  }
+  return rhythmLengthRows(DEFAULT_GAP_ROWS, rhythm);
+}
+
+function getFloatImageWidth(
+  input: Pick<
+    FloatGeometryInput,
+    "containerWidth" | "viewportWidth" | "rhythm" | "gap" | "imageWidthRatio" | "viewportImageCapRatio" | "maxWidthRows"
+  >,
+): number {
+  const imageWidthRatio = input.imageWidthRatio ?? FLOAT_IMAGE_WIDTH_RATIO;
+  const viewportImageCapRatio = input.viewportImageCapRatio ?? (1 / 3);
+  const preferred = snapDownToRhythm(Math.round(input.containerWidth * imageWidthRatio), input.rhythm);
+  const viewportCap = snapDownToRhythm(Math.floor(input.viewportWidth * viewportImageCapRatio), input.rhythm);
+  const copyCap = snapDownToRhythm(
+    Math.max(0, input.containerWidth - input.gap - getFloatCopyMinimum(input.viewportWidth, input.rhythm)),
+    input.rhythm,
+  );
+  const absoluteMaxWidth = rhythmLengthRows(input.maxWidthRows ?? FLOAT_IMAGE_MAX_WIDTH_ROWS, input.rhythm);
+  const softMinimum = getFloatImageMinimum(input.viewportWidth, input.rhythm);
+  const hardMinimum = rhythmLengthRows(5, input.rhythm);
+  const hardMaximum = Math.max(
+    hardMinimum,
+    Math.min(absoluteMaxWidth, viewportCap, copyCap > 0 ? copyCap : viewportCap),
+  );
+
+  if (hardMaximum <= softMinimum) return hardMaximum;
+  return clamp(Math.min(preferred, hardMaximum), softMinimum, hardMaximum);
+}
+
+function getFloatImageMinimum(viewportWidth: number, rhythm: VerticalRhythm): number {
+  return rhythmLengthRows(viewportWidth <= 600 ? FLOAT_IMAGE_MIN_PHONE_ROWS : FLOAT_IMAGE_MIN_DESKTOP_ROWS, rhythm);
+}
+
+function getFloatCopyMinimum(viewportWidth: number, rhythm: VerticalRhythm): number {
+  return rhythmLengthRows(viewportWidth <= 600 ? FLOAT_COPY_MIN_PHONE_ROWS : FLOAT_COPY_MIN_DESKTOP_ROWS, rhythm);
+}
+
+function getObstacleImageWidths(maximum: number, rhythm: VerticalRhythm): number[] {
+  const candidateRows = [0, 1, 2].map((offset) => Math.max(rhythm.rowHeight * 5, maximum - (offset * rhythm.rowHeight)));
+  return Array.from(new Set(candidateRows));
+}
+
+function snapImageHeight(
+  naturalHeight: number,
+  rhythm: VerticalRhythm,
+  layout?: ArticleImageAsset["layout"],
+): number {
+  const maxHeight = layout?.maxHeight ?? rhythm.rowHeight * 36;
+  // Cover may grow the frame to layout.minHeight. Contain/preserve must not —
+  // on narrow viewports the chosen width implies a short natural height, and
+  // stretching to minHeight leaves an empty outlined box around the pictogram.
+  if (layout?.crop === "cover") {
+    const minHeight = layout.minHeight ?? rhythm.rowHeight * 6;
+    const clampedHeight = clamp(naturalHeight, minHeight, maxHeight);
+    return snapPreferredHeightToRhythm(clampedHeight, rhythm, minHeight, maxHeight);
+  }
+  const hardMinimum = rhythm.rowHeight;
+  const capped = clamp(naturalHeight, hardMinimum, maxHeight);
+  return snapPreservedImageHeightToRhythm(capped, rhythm, hardMinimum, maxHeight);
+}
+
+function getImageAspectRatio(asset: Pick<ArticleImageAsset, "layout">): number {
+  if (asset.layout?.aspectRatio) return asset.layout.aspectRatio;
+  return 1;
+}
+
+function rhythmLengthRows(rows: number, rhythm: VerticalRhythm): number {
+  return rows * rhythm.rowHeight;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function isFeaturedBlogItem(item: PublicationItem, index?: number, mode?: string): boolean {
+  return mode === "blog" && index === 0 && Boolean(item.type === "article" || item.type === "brief");
+}