Compose poster headlines, a real far viewing scale, and named contrast lints

A region with headline: true lets its title grow past the role size to the
largest that fits the region's width and height, so a one-line poster or
sale sign no longer stops near 130 px on 1080p. viewing: far now sets every
role 1.5x larger rather than only raising floors. The catalog documents
valign (auto, top, center, bottom) and headline, and low_contrast_rendered
names the region, role and quoted copy it flags.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: gersham

src/compose/catalog.ts

@@ -55,6 +55,8 @@ export interface ComposeCatalog {
     image_src: string;
     shadow: string;
     outline: string;
+    valign: string;
+    headline: string;
     layered: string;
     envelope: string;
     viewing: string;
@@ -71,7 +73,7 @@ const PAGE_KEYS = [
 ];
 const REGION_FIELDS = [
   "eyebrow", "title", "subtitle", "text", "footer", "image", "video", "iframe", "webapp", "cards", "card", "table",
-  "enter", "stagger", "motion", "align", "valign", "fill", "color", "z", "shadow", "outline",
+  "enter", "stagger", "motion", "align", "valign", "fill", "color", "z", "shadow", "outline", "headline",
 ];
 
 export async function composeCatalog(): Promise<ComposeCatalog> {
@@ -289,6 +291,8 @@ export async function composeCatalog(): Promise<ComposeCatalog> {
       image_src: "local filesystem path relative to the spec file directory; iframe and webapp src may be a URL",
       shadow: 'Text over a page image or video with no fill gets a 1px unblurred drop shadow: #000000E6 on light type, #FFFFFFE6 on dark type. Set shadow to "none" or { x, y, color, blur? } to override. Optional blur is an integer 0 through 32; omit is 0 (unblurred offset fill). Auto media shadow stays 1 px unblurred. A card plate is backing, so type on a card does not get the automatic shadow.',
       outline: "outline is { width: 0.5-12, color } and is off unless set.",
+      valign: "valign places a region's content vertically: top, center or bottom; auto (default) centers it, and side-by-side regions with the same top and height share one scale and offset so their titles line up. Explicit top, center or bottom opts a region out of that row.",
+      headline: "headline: true lets the region's title grow past its role size to the largest that fits the region's width and height, one line per \\n line (posters, sale signs). Needs a title; other roles keep their sizes, and the whole pack still has to fit.",
       layered: "compose render writes one PNG per region plus manifest.json. --combined writes a flattened PNG for inspection. Default for agent work is layered.",
       envelope: "structured JSON, not pixels",
       viewing: viewingGuidance(),
@@ -333,6 +337,8 @@ export function formatComposeCatalog(catalog: ComposeCatalog): string {
     `image_src: ${catalog.rules.image_src}`,
     `shadow: ${catalog.rules.shadow}`,
     `outline: ${catalog.rules.outline}`,
+    `valign: ${catalog.rules.valign}`,
+    `headline: ${catalog.rules.headline}`,
     `layered: ${catalog.rules.layered}`,
     `viewing: ${catalog.rules.viewing}`,
     `lint: ${catalog.rules.lint}`,

src/compose/compose.test.ts

@@ -318,6 +318,24 @@ test("a type-only region uses one scale for every role", async () => {
   await rm(dir, { recursive: true, force: true });
 });
 
+test("a headline region grows a one-line title past the role wish, bounded by the region", async () => {
+  const dir = await testTemp("compose-headline-");
+  const base = { width: 1920, height: 1080, background: "#101010", text: "#FFFFFF" };
+  const titleSize = async (spec: Record<string, unknown>) => {
+    const result = await composeDocument({ ...base, ...spec }, { baseDir: dir });
+    return result.pages[0]!.quality.text.find((item) => item.role === "title")!.font_size;
+  };
+  const plain = await titleSize({ fullpage: { title: "SALE 20% OFF", align: "center", valign: "center" } });
+  const headline = await titleSize({ fullpage: { title: "SALE 20% OFF", align: "center", valign: "center", headline: true } });
+  assert.ok(plain <= Math.round(wishOf("title", 1080) * 1.35), `plain ${plain}`);
+  assert.ok(headline >= 220 && headline > plain * 1.4, `headline ${headline} plain ${plain}`);
+  assert.ok(headline <= 1080, `headline ${headline}`);
+  const far = await titleSize({ viewing: "far", fullpage: { title: "SALE 20% OFF", align: "center", valign: "center" } });
+  assert.ok(far > plain, `far ${far} plain ${plain}`);
+  await assertUsageRejects(() => composeDocument({ ...base, fullpage: { text: "x", headline: true } }, { baseDir: dir }), /headline needs a title/);
+  await rm(dir, { recursive: true, force: true });
+});
+
 test("missing font is usage_error", async () => {
   await assertUsageRejects(
     () => composeDocument({ ...page(), font: "DefinitelyNotAInstalledFamily" }, { baseDir: process.cwd() }),

src/compose/compose.ts

@@ -15,6 +15,7 @@ import { parseComposeSpec } from "./parse.js";
 import {
   SCALE_MAX,
   SCALE_MIN,
+  headlineMax,
   leadingOf,
   sizesFor,
   textHeight,
@@ -86,6 +87,8 @@ export interface ComposeQuality {
     ink: Box;
     font_size: number;
     family: string;
+    /** The run's plain copy, so a lint can name what it flags. */
+    text?: string;
   }>;
   fonts: Array<{ layer: string; family: string; fallback_from?: string; missing_codepoints: string[] }>;
   overlaps: Array<{ first: string; second: string; kind: "layer_layer"; area: number }>;
@@ -263,6 +266,7 @@ function chooseScale(
       title: title && title.role === "title" ? title.text : "",
       subtitle: subtitle && subtitle.role === "subtitle" ? subtitle.text : "",
       scale,
+      ...(layer.headline && title && title.role === "title" ? { titleMax: headlineMax(title.text, inner.h) } : {}),
     });
     const footerH = footerText ? textHeight(ctx, footerText, inner.w, ramp.footer, family, leadingOf(ramp.footer)) : 0;
     const footerGap = footerText ? Math.round(ramp.footer * 0.8) : 0;
@@ -830,6 +834,7 @@ async function paintLayer(
     title: title && title.role === "title" ? title.text : "",
     subtitle: subtitle && subtitle.role === "subtitle" ? subtitle.text : "",
     scale,
+    ...(layer.headline && title && title.role === "title" ? { titleMax: headlineMax(title.text, fitBox.h) } : {}),
   });
   if (shared.scale === undefined && !hasFluid && fixed.length) {
     const chosen = chooseScale(ctx, layer, fitBox, family, fixed, footerText);

src/compose/lint.test.ts

@@ -73,6 +73,8 @@ test("low_contrast_rendered fires on grey-on-grey and stays silent on a clean pa
     fullpage: { title: "Hello contrast" },
   });
   assert.ok(codes(findings).includes("low_contrast_rendered"), JSON.stringify(findings));
+  const flagged = findings.find((finding) => finding.code === "low_contrast_rendered")!;
+  assert.match(flagged.message, /fullpage title "Hello contrast" contrast/);
   const clean = await lintSpec(CLEAN);
   assert.equal(codes(clean).includes("low_contrast_rendered"), false);
 });

src/compose/lint.ts

@@ -137,7 +137,7 @@ export function lintComposedPage(args: {
           page_id: args.page_id,
           code: "low_contrast_rendered",
           id: run.layer,
-          message: `${args.page_id}: ${run.layer} contrast ${contrast.toFixed(2)}:1 is below 4.5:1.`,
+          message: `${args.page_id}: ${run.layer} ${run.role}${quotedExcerpt(run.text)} contrast ${contrast.toFixed(2)}:1 is below 4.5:1.`,
         });
       }
       if (overBusyImage(run.layer, run.ink, args.quality, args.pixels)) {
@@ -153,6 +153,13 @@ export function lintComposedPage(args: {
   return findings;
 }
 
+/** A short quote of the flagged copy, so the agent knows which text to change. */
+function quotedExcerpt(text: string | undefined): string {
+  const flat = (text ?? "").replace(/\s+/g, " ").trim();
+  if (!flat) return "";
+  return ` "${flat.length > 40 ? `${flat.slice(0, 40)}…` : flat}"`;
+}
+
 function countSpecWords(value: unknown): number {
   if (typeof value === "string") {
     const bits = value.trim().split(/\s+/);

src/compose/parse.ts

@@ -62,7 +62,7 @@ const REGION_KEYS = new Set([
   "image", "video", "iframe", "webapp",
   "cards", "card", "table",
   "enter", "stagger", "motion",
-  "align", "valign", "fill", "color", "z", "shadow", "outline",
+  "align", "valign", "fill", "color", "z", "shadow", "outline", "headline",
 ]);
 const SHADOW_KEYS = new Set(["x", "y", "color", "blur"]);
 const OUTLINE_KEYS = new Set(["width", "color"]);
@@ -365,6 +365,9 @@ function parseRegion(name: RegionName, value: unknown, canvas: { width: number;
   if (!(ALIGN as readonly string[]).includes(String(align))) fail(`${name}.align must be left|center|right`);
   const valign = value.valign == null ? "auto" : value.valign;
   if (!(VALIGN as readonly string[]).includes(String(valign))) fail(`${name}.valign must be auto|top|center|bottom`);
+  if (value.headline != null && typeof value.headline !== "boolean") fail(`${name}.headline must be true or false`);
+  const headline = value.headline === true;
+  if (headline && content.title == null) fail(`${name}.headline needs a title`);
   let enter: PrimitiveEnter | null = null;
   if (value.enter != null) {
     if (typeof value.enter !== "string" || !(ENTER_TYPES as readonly string[]).includes(value.enter)) {
@@ -425,6 +428,7 @@ function parseRegion(name: RegionName, value: unknown, canvas: { width: number;
     overMedia: Boolean(defaults.image || defaults.video),
     align: align as Align,
     valign: valign as Valign,
+    headline,
     font: defaults.font,
     text: defaults.text,
     muted: defaults.muted,
@@ -464,6 +468,7 @@ function backgroundLayer(canvas: { width: number; height: number }, defaults: Pa
     overMedia: false,
     align: "left",
     valign: "top",
+    headline: false,
     font: defaults.font,
     text: defaults.text,
     muted: defaults.muted,
@@ -502,6 +507,7 @@ function logoLayer(canvas: { width: number; height: number }, defaults: PageDefa
     overMedia: Boolean(defaults.image || defaults.video),
     align: "left",
     valign: "top",
+    headline: false,
     font: defaults.font,
     text: defaults.text,
     muted: defaults.muted,

src/compose/type.ts

@@ -14,6 +14,11 @@ export const VIEWING_XHEIGHT_RATIO: Record<ViewingDistance, number> = {
 
 /** Fallback x-height as a fraction of font size when metrics are missing. */
 export const XHEIGHT_FALLBACK = 0.52;
+/**
+ * Role wishes per viewing distance. Far-away readers get larger type, not just
+ * a higher floor; near and mid keep the reference ramp.
+ */
+export const VIEWING_WISH_SCALE: Record<ViewingDistance, number> = { near: 1, mid: 1, far: 1.5 };
 export const SCALE_MIN = 0.65;
 export const SCALE_MAX = 1.35;
 export const REFERENCE_CANVAS = { width: 1920, height: 1080 } as const;
@@ -75,18 +80,20 @@ export function sizeFor(
     root: number;
     viewing: ViewingDistance;
     scale?: number;
+    /** Headline: a line-fit role may grow past its wish up to this size, as wide as the region allows. */
+    max?: number;
   },
 ): number {
   const spec = ROLE[args.role];
-  const baseWish = wishOf(args.role, args.root);
+  const baseWish = Math.round(wishOf(args.role, args.root) * VIEWING_WISH_SCALE[args.viewing]);
   const floor = floorOf(args.role, args.root, args.viewing);
   const scale = args.scale ?? 1;
   const ceiling = Math.max(floor, Math.round(baseWish * SCALE_MAX));
   const wish = Math.min(ceiling, Math.max(floor, Math.round(baseWish * scale)));
   if (spec.fit !== "line" || !args.text) return wish;
   const lines = String(args.text).split("\n");
   let lo = floor;
-  let hi = wish;
+  let hi = args.max !== undefined ? Math.max(floor, Math.round(args.max * scale)) : wish;
   let best = floor;
   while (lo <= hi) {
     const mid = Math.floor((lo + hi) / 2);
@@ -122,12 +129,14 @@ export function sizesFor(
     title?: string;
     subtitle?: string;
     scale?: number;
+    /** Headline regions: the title's size limit from the region height. */
+    titleMax?: number;
   },
 ): TypeRamp {
   const shared = { family: args.family, width: args.width, root: args.root, viewing: args.viewing, scale: args.scale ?? 1 };
   return {
     eyebrow: sizeFor(ctx, { role: "eyebrow", text: args.eyebrow, ...shared }),
-    title: sizeFor(ctx, { role: "title", text: args.title, ...shared }),
+    title: sizeFor(ctx, { role: "title", text: args.title, ...shared, ...(args.titleMax !== undefined ? { max: args.titleMax } : {}) }),
     subtitle: sizeFor(ctx, { role: "subtitle", text: args.subtitle, ...shared }),
     text: sizeFor(ctx, { role: "text", ...shared }),
     footer: sizeFor(ctx, { role: "footer", ...shared }),
@@ -177,5 +186,12 @@ export function textHeight(
 }
 
 export function viewingGuidance(): string {
-  return 'optional page "near"|"mid"|"far"; default mid. Type floors use that x-height at layout (1080p mid body wish is ~45 px); lint warns too_small_for_distance if a node still undershoots 0.7%/1.2%/2.0% of the shorter edge.';
+  return 'optional page "near"|"mid"|"far"; default mid. far sets every role 1.5x larger (1080p far body ~68 px, title ~195 px) and every distance raises type floors to its x-height; lint warns too_small_for_distance if a node still undershoots 0.7%/1.2%/2.0% of the shorter edge.';
+}
+
+/** The largest title size a headline region can hold: its lines stacked in the region height. */
+export function headlineMax(title: string | undefined, regionHeight: number): number | undefined {
+  if (!title) return undefined;
+  const lines = Math.max(1, String(title).split("\n").length);
+  return Math.floor(regionHeight / (lines * 1.28));
 }

src/compose/types.ts

@@ -138,6 +138,8 @@ export interface LayerSpec {
   overMedia: boolean;
   align: Align;
   valign: Valign;
+  /** Region title grows to the largest size that fits the region, one line per line. */
+  headline: boolean;
   font: string | null;
   text: string;
   muted: string;