@appshoteditor/shot-dsl 0.3.0 → 0.4.0

package/src/compose.ts

@@ -1,7 +1,25 @@
-import type { BackgroundJSON, LayerJSON, Template } from './types';
-import { makeTextLayer, makeScreen, makeTemplate } from './builders';
+import type { BackgroundJSON, ColorStop, LayerJSON, Template } from './types';
+import { makeTextLayer, makeShapeLayer, makeScreen, makeTemplate } from './builders';
 import { makeDeviceFrameLayer } from './frames';
 import { getDeviceFrame, deviceClassForDeviceId } from './device-frames';
+import { generateLayerId } from './validate';
+import {
+	NO_TANGENT,
+	focusCorners,
+	focusReach,
+	focusXExtent,
+	inTangentZone,
+	rectsOverlap,
+	rotatedBox,
+	solveVertical,
+	subjectPointToCanvas,
+	visibleXExtent,
+	type BleedPreference,
+	type FocusBand,
+	type Subject,
+	type VerticalResult
+} from './layout-system';
+import { darken, isHexColor, lighten, mixHex, readableTextOn, rgba } from './color';
 
 /**
  * Editor-unit canvas dimensions for a device, by frame class — so a plan that mixes iPhone, iPad,
@@ -9,7 +27,7 @@ import { getDeviceFrame, deviceClassForDeviceId } from './device-frames';
  * Page Setup presets (phone 280×608, tablet 450×600, laptop/desktop 608×380). Export scales these
  * up to the real App Store pixel sizes.
  */
-function canvasDimsForDevice(deviceId: string): { width: number; height: number } {
+export function canvasDimsForDevice(deviceId: string): { width: number; height: number } {
 	switch (getDeviceFrame(deviceId)?.category) {
 		case 'tablet':
 			return { width: 450, height: 600 };
@@ -24,15 +42,82 @@ function canvasDimsForDevice(deviceId: string): { width: number; height: number
 
 /**
  * Screen layout variants:
- * - `text-top` (default): headline (+ subheadline) at the top, device below, bleeding off the bottom.
- * - `text-bottom`: device at the top bleeding off the TOP edge, text block anchored to the bottom.
- * - `device-bleed`: text at the top, an oversized device (~95% of the width) bleeding heavily off
- *   the bottom — the "hero" look.
+ * - `text-top` (default): headline (+ subheadline) at the top, device below.
+ * - `text-bottom`: device at the top (bleeding off the TOP edge when it bleeds), text block at the bottom.
+ * - `device-bleed`: text at the top, the device (≤ 90% of the width) pushed low and bleeding more — the "hero" look.
  */
 export type ComposeLayout = 'text-top' | 'text-bottom' | 'device-bleed';
-
 export const COMPOSE_LAYOUTS: readonly ComposeLayout[] = ['text-top', 'text-bottom', 'device-bleed'];
 
+/**
+ * How a screenshot is presented:
+ * - `device` (default): inside a device frame mockup.
+ * - `frameless`: the bare screenshot with rounded corners + a soft shadow.
+ * - `zoom`: a magnified crop of the screen's selling UI (`crop`, else the `focus` band), rounded + shadow.
+ */
+export type ComposePresentation = 'device' | 'frameless' | 'zoom';
+export const COMPOSE_PRESENTATIONS: readonly ComposePresentation[] = ['device', 'frameless', 'zoom'];
+
+/** `auto` (default): the no-tangent rule picks clear-with-margin or a decisive bleed. */
+export type ComposeBleed = BleedPreference;
+export const COMPOSE_BLEEDS: readonly ComposeBleed[] = ['auto', 'none', 'deep'];
+
+/** Fonts the editor offers (Inter is web-loaded; the rest are system fonts). */
+export const COMPOSE_FONTS: readonly string[] = [
+	'Inter',
+	'Arial',
+	'Helvetica',
+	'Georgia',
+	'Times New Roman',
+	'Courier New',
+	'Verdana',
+	'Trebuchet MS',
+	'Impact',
+	'Comic Sans MS'
+];
+
+/** Fractions (0–1) of the screenshot: a crop rectangle for `zoom`. */
+export interface ComposeCrop {
+	x: number;
+	y: number;
+	w: number;
+	h: number;
+}
+
+/** Set-wide background system, used for screens that omit `background`. */
+export interface ComposePalette {
+	/** `family`: every screen shares one gradient through `colors`. `sequence`: screen i uses colors[i % n]. */
+	mode: 'family' | 'sequence';
+	colors: string[];
+}
+
+export interface ComposePanorama {
+	/** Runs of adjacent screen indices sharing one continuous background, e.g. [[0, 1], [2, 3]]. */
+	spans: number[][];
+	/**
+	 * Devices that cross a seam into the next screen: `true` = the first screen of EVERY span, or a
+	 * list of screen indices (each must be the first screen of a span). Default none. More than one
+	 * straddle per set is allowed but lint-warned (`panorama-straddle-count`).
+	 */
+	straddle?: boolean | number[];
+	/** Soft decorative circles straddling each seam. Default `orbs`. */
+	decoration?: 'orbs' | 'none';
+}
+
+/** Plan-level style (all optional; an empty style composes exactly like a plan without one). */
+export interface ComposeStyle {
+	presentation?: ComposePresentation;
+	/** Degrees (clockwise) for the accented screens listed in `tiltScreens`. Default 0. */
+	tilt?: number;
+	/** Screen indices that get `tilt`. Default: none. */
+	tiltScreens?: number[];
+	bleed?: ComposeBleed;
+	palette?: ComposePalette;
+	panorama?: ComposePanorama;
+	/** Font family for all text (one of COMPOSE_FONTS). Default Inter. */
+	font?: string;
+}
+
 /** One screen's worth of plan input (the skill decides these per benefit). */
 export interface ComposeScreenPlan {
 	headline: string;
@@ -43,9 +128,23 @@ export interface ComposeScreenPlan {
 	subheadlineColor?: string;
 	/** Defaults to `text-top`. */
 	layout?: ComposeLayout;
-	background: BackgroundJSON;
+	/**
+	 * Required unless the plan has `style.palette`. In a panorama span every screen shows the span's
+	 * FIRST screen's background.
+	 */
+	background?: BackgroundJSON;
 	screenshot: { url: string; width: number; height: number };
 	deviceId: string;
+	/** Fractions of the screenshot height that must stay visible (the selling UI). */
+	focus?: FocusBand;
+	/** Zoom crop (fractions of the screenshot); defaults to the focus band. */
+	crop?: ComposeCrop;
+	/** Overrides `style.presentation` for this screen. */
+	presentation?: ComposePresentation;
+	/** Overrides the style tilt for this screen (degrees, clockwise). */
+	tilt?: number;
+	/** Short social-proof pill above the headline, e.g. "Teacher-approved". */
+	badge?: string;
 }
 
 export interface ComposePlan {
@@ -53,6 +152,59 @@ export interface ComposePlan {
 	screens: ComposeScreenPlan[];
 	canvasWidth?: number;
 	canvasHeight?: number;
+	style?: ComposeStyle;
+}
+
+export interface ComposeWarning {
+	/** Screen index, when the warning is about one screen. */
+	screen?: number;
+	code:
+		| 'headline-words'
+		| 'headline-lines'
+		| 'subheadline-lines'
+		| 'tilt-count'
+		| 'panorama-seam'
+		| 'straddle-skipped'
+		| 'tilt-reduced'
+		| 'panorama-straddle-count'
+		| 'zoom-focus-cropped'
+		| 'badge-long';
+	message: string;
+}
+
+/** Per-screen geometry summary (canvas-relative), for reports and tests. */
+export interface ComposeScreenMetrics {
+	index: number;
+	presentation: ComposePresentation;
+	layout: ComposeLayout;
+	/** Screens with the same group share scale, baseline and far-edge treatment. */
+	group: string;
+	/** Rendered subject scale (device scaleX; image scaleX for frameless/zoom). */
+	scale: number;
+	/** Rendered (unrotated) subject width ÷ W. */
+	widthFraction: number;
+	/** Subject's rotated bounding-box top / bottom ÷ H. */
+	top: number;
+	bottom: number;
+	/** Far-edge overshoot ÷ H (> 0 bleeds off the canvas). */
+	overshoot: number;
+	/** Far-edge overshoot ÷ the subject's rendered (rotated) height. */
+	bleedFraction: number;
+	mode: 'clear' | 'bleed';
+	/** True if the far edge sits in the forbidden "just touching" band (never, by construction). */
+	tangent: boolean;
+	/** Headline font size ÷ W. */
+	headlineSize: number;
+	/** Headline box top ÷ H (identical across a set by construction). */
+	headlineTop: number;
+	tilt: number;
+	/** Horizontal centre ÷ W (≠ 0.5 for a straddling panorama device). */
+	centerX: number;
+}
+
+export interface ComposeReport {
+	warnings: ComposeWarning[];
+	screens: ComposeScreenMetrics[];
 }
 
 // ---------------------------------------------------------------------------
@@ -66,20 +218,73 @@ export interface ComposePlan {
  * (tablet, laptop) it's capped by the height so text doesn't swallow a landscape canvas.
  */
 const TYPE_UNIT_HEIGHT_CAP = 0.55; // unit = min(W, 0.55·H)
-const HEADLINE_SIZE = 0.085; // × unit — for headlines that fit in ≤ 2 lines
-const HEADLINE_SIZE_LONG = 0.072; // × unit — fallback when the headline would wrap to 3+ lines
+/** × unit — ONE headline size for the whole set (copy that doesn't fit is a lint warning, never a shrink). */
+export const HEADLINE_SIZE = 0.085;
 const HEADLINE_LINE_HEIGHT = 1.1;
 const SUBHEADLINE_RATIO = 0.55; // subheadline size ÷ headline size
 const SUBHEADLINE_LINE_HEIGHT = 1.25;
 const SUBHEADLINE_OPACITY = 0.85;
 const TEXT_WIDTH = 0.84; // × W → 8% side padding each side
-/** Rough average glyph advance for Inter at heavy weights, as a fraction of the font size. */
-const AVG_CHAR_WIDTH = 0.58;
+/**
+ * Conservative per-font text metrics for line-wrap estimates (and so the reserved text area):
+ * px per character "unit" (see `charUnits`; 1 unit ≈ an average lowercase letter) × the font size.
+ * Calibrated from node-canvas measurements of macOS system fonts (bold, mixed case, ALL CAPS,
+ * narrow/wide stress strings) + ~10% headroom, so an estimate of N lines never renders as N+1;
+ * see src/lib/utils/composeFonts.canvas.test.ts in the app. Inter (web font, not installed for the
+ * measurement) is set ~10% wider than Arial. Courier New is monospace: every character is 1 unit.
+ */
+export const FONT_CHAR_WIDTH: Readonly<Record<string, number>> = {
+	Inter: 0.66,
+	Arial: 0.64,
+	Helvetica: 0.64,
+	Georgia: 0.72,
+	'Times New Roman': 0.63,
+	'Courier New': 0.66,
+	Verdana: 0.76,
+	'Trebuchet MS': 0.68,
+	Impact: 0.64,
+	'Comic Sans MS': 0.76
+};
+const MONOSPACE_FONTS = new Set(['Courier New']);
+const AVG_CHAR_WIDTH = FONT_CHAR_WIDTH.Inter;
+
+/** A font name (→ FONT_CHAR_WIDTH) or a raw px-per-unit factor. */
+export type TextMetrics = string | number;
+const metricsOf = (m: TextMetrics) =>
+	typeof m === 'number' ? { charWidth: m, mono: false } : { charWidth: FONT_CHAR_WIDTH[m] ?? AVG_CHAR_WIDTH, mono: MONOSPACE_FONTS.has(m) };
 
 const EDGE_MARGIN = 0.055; // × H — gap between the text block and the canvas edge
 const TEXT_GAP = 0.3; // × headline font size — headline ↔ subheadline gap
 const DEVICE_GAP = 0.04; // × unit — text block ↔ device gap
 
+/** Copy rules (lint). */
+export const COPY_RULES = { headlineMaxWords: 5, headlineMaxLines: 2, subheadlineMaxLines: 1, maxTiltedScreens: 2 } as const;
+
+// Badge pill (social proof), reserved as a row above the headline set-wide when any screen has one.
+const BADGE_FONT = 0.36; // × headline size
+const BADGE_PAD_X = 1.1; // × badge font
+const BADGE_HEIGHT = 2.1; // × badge font
+const BADGE_GAP = 0.45; // × headline size — badge ↔ headline
+const BADGE_MAX_CHARS = 28;
+
+// Frameless / zoom styling.
+const FRAMELESS_WIDTH = 0.9; // × the layout's device width target (no bezel → a touch narrower)
+const FRAMELESS_RADIUS = 0.1; // × rendered width
+const ZOOM_WIDTH = 0.88; // × W
+const ZOOM_RADIUS = 0.05; // × W
+const ZOOM_MAX_MAG = 2; // focus-derived zoom: at most 2× the full-width fit
+const ZOOM_MIN_ASPECT = 0.5; // card height ≥ half its width
+const SHADOW = { color: 'rgba(0,0,0,0.28)', blur: 0.07, offsetY: 0.025 }; // blur/offset × W
+
+// Panorama.
+const STRADDLE_OVERLAP = 0.18; // × the device's rendered bounding-box width that crosses the seam
+const STRADDLE_MIN = 0.06; // below this a straddle is not worth it (skipped + warning)
+const MAX_STRADDLES = 1; // seam crossings per set before a lint warning
+const ORB_RADIUS = 0.34; // × W
+const ORB_Y = 0.7; // × H
+const ORB_MIN_RADIUS = 0.08; // × W — smaller than this, the orb is dropped
+const ORB_TEXT_GAP = 0.02; // × H — orbs keep this far from a text block
+
 interface LayoutSpec {
 	/** Target rendered device width as a fraction of the canvas width. */
 	deviceWidth: number;
@@ -92,146 +297,1014 @@ interface LayoutSpec {
 const LAYOUTS: Record<ComposeLayout, LayoutSpec> = {
 	'text-top': { deviceWidth: 0.86, maxBleed: 0.2, minDeviceTop: 0 },
 	'text-bottom': { deviceWidth: 0.9, maxBleed: 0.2, minDeviceTop: 0 },
-	'device-bleed': { deviceWidth: 0.95, maxBleed: 0.4, minDeviceTop: 0.28 }
+	// Capped at NO_TANGENT.maxWidth (90% W — a 5% side margin); the hero differs by sitting lower.
+	'device-bleed': { deviceWidth: 0.9, maxBleed: 0.4, minDeviceTop: 0.28 }
 };
 
-/** Greedy word-wrap estimate of how many lines `text` takes at `fontSize` in a box `width` wide. */
-function estimateLines(text: string, fontSize: number, width: number): number {
-	const maxChars = Math.max(1, Math.floor(width / (fontSize * AVG_CHAR_WIDTH)));
+/**
+ * Relative advance of a character (1 = an average lowercase letter). Capitals and m/w are wide,
+ * i/l/punctuation narrow — so ALL-CAPS or "Mm Ww" copy isn't under-estimated.
+ */
+function charUnits(ch: string): number {
+	if (ch === ' ') return 0.5;
+	if ("iljI.,:;!|'’".includes(ch)) return 0.5;
+	if ('ftr()[]-–'.includes(ch)) return 0.7;
+	if ('mwMW'.includes(ch)) return 1.55;
+	if (ch >= 'A' && ch <= 'Z') return 1.3;
+	return 1;
+}
+
+/** Estimated rendered width of `text` (single line) — the width model behind `estimateLines`. */
+export function estimateTextWidth(text: string, fontSize: number, metrics: TextMetrics = 'Inter'): number {
+	const { charWidth, mono } = metricsOf(metrics);
+	return [...text].reduce((sum, ch) => sum + (mono ? 1 : charUnits(ch)), 0) * fontSize * charWidth;
+}
+
+/**
+ * Greedy word-wrap estimate (Fabric Textbox semantics: wrap at spaces, break over-long words) of how
+ * many lines `text` takes at `fontSize` in a box `width` wide, in the font `metrics` (a COMPOSE_FONTS
+ * name, or a raw px-per-unit factor).
+ */
+export function estimateLines(text: string, fontSize: number, width: number, metrics: TextMetrics = 'Inter'): number {
+	const { charWidth, mono } = metricsOf(metrics);
+	const unit = fontSize * charWidth;
+	const maxUnits = Math.max(1, width / unit);
+	const cu = (ch: string) => (mono ? 1 : charUnits(ch));
+	const units = (w: string) => [...w].reduce((sum, ch) => sum + cu(ch), 0);
 	let lines = 0;
 	for (const paragraph of text.split('\n')) {
 		let current = 0;
 		lines++;
 		for (const word of paragraph.split(/\s+/).filter(Boolean)) {
-			const len = word.length;
+			const len = units(word);
 			if (current === 0) {
 				current = len;
-			} else if (current + 1 + len <= maxChars) {
-				current += 1 + len;
+			} else if (current + cu(' ') + len <= maxUnits) {
+				current += cu(' ') + len;
 			} else {
 				lines++;
 				current = len;
 			}
 			// A single word longer than a line wraps mid-word in Fabric's Textbox.
-			while (current > maxChars) {
+			while (current > maxUnits) {
 				lines++;
-				current -= maxChars;
+				current -= maxUnits;
 			}
 		}
 	}
 	return Math.max(1, lines);
 }
 
-interface TextBlock {
+/** Set typography for one canvas size. */
+interface Typography {
+	W: number;
+	H: number;
+	unit: number;
 	headlineSize: number;
-	headlineHeight: number;
 	subSize: number;
+	textWidth: number;
+	margin: number;
+	deviceGap: number;
+	/** Reserved badge row (0 when no screen of this size has a badge). */
+	badgeRow: number;
+	badgeFont: number;
+	/** The set font (text metrics: FONT_CHAR_WIDTH). */
+	font: string;
+	/** Reserved text-block height = the TALLEST block among screens of this size. */
+	textArea: number;
+}
+
+interface TextBlock {
+	headlineLines: number;
+	headlineHeight: number;
+	subLines: number;
 	subHeight: number;
 	gap: number;
 	height: number;
 }
 
-function measureTextBlock(screen: ComposeScreenPlan, unit: number, textWidth: number): TextBlock {
-	let headlineSize = unit * HEADLINE_SIZE;
-	if (estimateLines(screen.headline, headlineSize, textWidth) > 2) headlineSize = unit * HEADLINE_SIZE_LONG;
-	const headlineHeight =
-		estimateLines(screen.headline, headlineSize, textWidth) * headlineSize * HEADLINE_LINE_HEIGHT;
-
+function measureTextBlock(screen: ComposeScreenPlan, t: Omit<Typography, 'textArea'>): TextBlock {
+	const headlineLines = estimateLines(screen.headline, t.headlineSize, t.textWidth, t.font);
+	const headlineHeight = headlineLines * t.headlineSize * HEADLINE_LINE_HEIGHT;
 	const hasSub = !!screen.subheadline?.trim();
-	const subSize = headlineSize * SUBHEADLINE_RATIO;
-	const subHeight = hasSub
-		? estimateLines(screen.subheadline!, subSize, textWidth) * subSize * SUBHEADLINE_LINE_HEIGHT
-		: 0;
-	const gap = hasSub ? headlineSize * TEXT_GAP : 0;
-	return { headlineSize, headlineHeight, subSize, subHeight, gap, height: headlineHeight + gap + subHeight };
+	const subLines = hasSub ? estimateLines(screen.subheadline!, t.subSize, t.textWidth, t.font) : 0;
+	const subHeight = subLines * t.subSize * SUBHEADLINE_LINE_HEIGHT;
+	const gap = hasSub ? t.headlineSize * TEXT_GAP : 0;
+	return { headlineLines, headlineHeight, subLines, subHeight, gap, height: t.badgeRow + headlineHeight + gap + subHeight };
+}
+
+/** Everything decided per screen before layers are built. */
+interface ResolvedScreen {
+	index: number;
+	plan: ComposeScreenPlan;
+	W: number;
+	H: number;
+	layout: ComposeLayout;
+	presentation: ComposePresentation;
+	tilt: number;
+	background: BackgroundJSON;
+	backgroundFromStyle: boolean;
+	typo: Typography;
+	block: TextBlock;
+	group: string;
+}
+
+const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+
+function normalizeFocus(focus: FocusBand | undefined): FocusBand | undefined {
+	if (!focus || typeof focus.top !== 'number' || typeof focus.bottom !== 'number') return undefined;
+	const top = clamp01(Math.min(focus.top, focus.bottom));
+	const bottom = clamp01(Math.max(focus.top, focus.bottom));
+	return bottom > top ? { top, bottom } : undefined;
+}
+
+/** A background's colour stops (solid → a subtle two-stop ramp around it). */
+function backgroundStops(bg: BackgroundJSON): ColorStop[] {
+	const stops = bg.gradient?.colorStops;
+	if (bg.type === 'gradient' && stops && stops.length > 0) return stops;
+	// v1 gradients list bare `colors` (evenly spaced), like the editor's migrateScreenLayersJSON.
+	const v1 = bg.gradient?.colors?.filter(isHexColor) ?? [];
+	if (bg.type === 'gradient' && v1.length > 0) return evenStops(v1.length === 1 ? [v1[0], v1[0]] : v1);
+	const c = isHexColor(bg.color) ? bg.color : '#1F2937';
+	return [
+		{ offset: 0, color: lighten(c, 0.14) },
+		{ offset: 1, color: darken(c, 0.14) }
+	];
+}
+
+function evenStops(colors: string[]): ColorStop[] {
+	return colors.map((color, i) => ({ offset: colors.length > 1 ? i / (colors.length - 1) : 0, color }));
+}
+
+const linear = (colorStops: ColorStop[]): BackgroundJSON => ({ type: 'gradient', gradient: { type: 'linear', colorStops } });
+
+/** Background from the plan-level palette (null when there is none / it's unusable). */
+function paletteBackground(palette: ComposePalette | undefined, index: number): BackgroundJSON | null {
+	const colors = (palette?.colors ?? []).filter(isHexColor);
+	if (!palette || colors.length === 0) return null;
+	if (palette.mode === 'sequence') {
+		const c = colors[index % colors.length];
+		return linear([
+			{ offset: 0, color: lighten(c, 0.16) },
+			{ offset: 1, color: c }
+		]);
+	}
+	return linear(evenStops(colors.length === 1 ? [colors[0], darken(colors[0], 0.22)] : colors));
+}
+
+/** Colour of a ramp of `stops` at parameter t ∈ [0, 1] (non-hex stops are ignored). */
+function colorAt(stops: ColorStop[], t: number): string {
+	const sorted = stops.filter((c) => isHexColor(c.color)).sort((a, b) => a.offset - b.offset);
+	if (sorted.length === 0) return '#1F2937';
+	if (t <= sorted[0].offset) return sorted[0].color;
+	for (let i = 1; i < sorted.length; i++) {
+		const a = sorted[i - 1];
+		const b = sorted[i];
+		if (t <= b.offset) return mixHex(a.color, b.color, b.offset > a.offset ? (t - a.offset) / (b.offset - a.offset) : 1);
+	}
+	return sorted[sorted.length - 1].color;
+}
+
+type Coords = { x1: number; y1: number; x2: number; y2: number };
+
+/** Ramp parameter (0–1, padded at the ends) of point (x, y) on a linear gradient from p1 to p2. */
+function rampT(c: Coords, x: number, y: number): number {
+	const dx = c.x2 - c.x1;
+	const dy = c.y2 - c.y1;
+	const len2 = dx * dx + dy * dy || 1;
+	return clamp01(((x - c.x1) * dx + (y - c.y1) * dy) / len2);
+}
+
+/** Where the editor draws an angle-based gradient over a w×h box (mirrors `deserializeBackground`). */
+function angleCoords(angle: number | undefined, w: number, h: number): Coords {
+	const rad = (((angle || 180) - 90) * Math.PI) / 180;
+	return {
+		x1: (0.5 + Math.cos(rad) * 0.5) * w,
+		y1: (0.5 + Math.sin(rad) * 0.5) * h,
+		x2: (0.5 - Math.cos(rad) * 0.5) * w,
+		y2: (0.5 - Math.sin(rad) * 0.5) * h
+	};
 }
 
 /**
- * Deterministically assemble a Template from a plan. Each screen gets a background, a large
- * device frame carrying its screenshot and a bold headline (+ optional subheadline), arranged per the screen's
- * `layout`. All geometry is derived from the canvas size. Text layers are marked editable so the
- * user can tweak them in the editor. Claude decides the plan (benefit, copy, device, palette,
- * layout); this turns it into valid DSL.
+ * Colour of a LINEAR screen background at canvas point (x, y), placed exactly as the editor draws it
+ * (mirrors `deserializeBackground`: explicit coords, else `angle` — default 180°, i.e. offset 0 at
+ * the BOTTOM edge). Radial gradients are not modelled (they are sampled as if linear): auto-contrast
+ * only ever samples palette backgrounds, which are always linear, and panorama spans, which reject
+ * radial backgrounds.
  */
-export function composeTemplate(plan: ComposePlan): Template {
-	const screens = plan.screens.map((screen) => {
-		// Per-screen canvas dims: honor explicit plan-level dims (backward compatible — same as the
-		// old single-size behavior), else derive from the screen's device class so a mixed-device
-		// plan gets the correct aspect per screen.
-		const explicit = plan.canvasWidth != null || plan.canvasHeight != null;
-		const { width: W, height: H } = explicit
-			? { width: plan.canvasWidth ?? 280, height: plan.canvasHeight ?? 600 }
-			: canvasDimsForDevice(screen.deviceId);
+export function sampleBackground(bg: BackgroundJSON, W: number, H: number, x: number, y: number): string {
+	if (bg.type !== 'gradient' || !bg.gradient) return isHexColor(bg.color) ? bg.color : '#1F2937';
+	return colorAt(backgroundStops(bg), rampT(bg.gradient.coords ?? angleCoords(bg.gradient.angle, W, H), x, y));
+}
 
-		const layout: ComposeLayout = screen.layout ?? 'text-top';
-		const spec = LAYOUTS[layout] ?? LAYOUTS['text-top'];
-		const unit = Math.min(W, H * TYPE_UNIT_HEIGHT_CAP);
-		const textWidth = W * TEXT_WIDTH;
-		const margin = H * EDGE_MARGIN;
-		const deviceGap = unit * DEVICE_GAP;
-		const block = measureTextBlock(screen, unit, textWidth);
-
-		// Text block vertical extent.
-		const blockTop = layout === 'text-bottom' ? H - margin - block.height : margin;
-
-		// Device size: target a fraction of the canvas width, but never let more than `maxBleed` of
-		// the device fall off-canvas (keeps squat tablet/laptop canvases sane).
-		const device = getDeviceFrame(screen.deviceId);
-		if (!device) throw new Error(`Unknown device: ${screen.deviceId}`);
-		const { width: fw, height: fh } = device.imageDimensions;
-		let scale: number;
-		let centerY: number;
-		if (layout === 'text-bottom') {
-			const deviceBottom = blockTop - deviceGap;
-			scale = Math.min((W * spec.deviceWidth) / fw, deviceBottom / (1 - spec.maxBleed) / fh);
-			centerY = deviceBottom - (fh * scale) / 2; // top edge bleeds off the top when tall
-		} else {
-			const deviceTop = Math.max(margin + block.height + deviceGap, H * spec.minDeviceTop);
-			scale = Math.min((W * spec.deviceWidth) / fw, (H - deviceTop) / (1 - spec.maxBleed) / fh);
-			centerY = deviceTop + (fh * scale) / 2; // bottom edge bleeds off the bottom when tall
+/** What a panorama span paints across its N·W × H rect. */
+type SpanFill = { kind: 'solid'; color: string } | { kind: 'linear'; stops: ColorStop[]; coords: Coords };
+
+/**
+ * The span-start screen's background, stretched across the whole span, keeping its colours, stop
+ * offsets and `angle` (an angle-less gradient runs diagonally corner to corner; a solid colour stays
+ * solid). Rejects what can't run across screens: radial gradients and explicit per-screen `coords`.
+ */
+function spanFillFor(bg: BackgroundJSON, first: number, N: number, W: number, H: number): SpanFill {
+	if (bg.type !== 'gradient' || !bg.gradient) return { kind: 'solid', color: isHexColor(bg.color) ? bg.color : '#1F2937' };
+	const at = `panorama span starting at screen ${first + 1}`;
+	if (bg.gradient.type === 'radial') {
+		throw new Error(`${at}: a radial gradient background can't run across screens — use a linear gradient or a solid colour`);
+	}
+	if (bg.gradient.coords) {
+		throw new Error(`${at}: explicit gradient \`coords\` are per-screen and can't span screens — use \`angle\` (or omit it) instead`);
+	}
+	const stops = backgroundStops(bg);
+	const coords = bg.gradient.angle != null ? angleCoords(bg.gradient.angle, N * W, H) : { x1: 0, y1: 0, x2: N * W, y2: H };
+	return { kind: 'linear', stops, coords };
+}
+
+/** Colour of a span fill at point (x, y) of span screen k. */
+function samplePanorama(fill: SpanFill, k: number, W: number, x: number, y: number): string {
+	return fill.kind === 'solid' ? fill.color : colorAt(fill.stops, rampT(fill.coords, k * W + x, y));
+}
+
+/** The subject (what is placed under the text) of a framed / frameless screen. */
+function subjectFor(r: ResolvedScreen): Subject {
+	if (r.presentation === 'device') {
+		const device = getDeviceFrame(r.plan.deviceId);
+		if (!device) throw new Error(`Unknown device: ${r.plan.deviceId}`);
+		const { width, height } = device.imageDimensions;
+		return { width, height, screen: { ...device.screenBounds } };
+	}
+	const { width, height } = r.plan.screenshot;
+	return { width, height, screen: { x: 0, y: 0, width, height } };
+}
+
+interface Placement {
+	cx: number;
+	cy: number;
+	scale: number;
+	angle: number;
+	/** Rendered rotated bounding box. */
+	boxWidth: number;
+	boxHeight: number;
+	vertical: VerticalResult;
+	subject: Subject;
+	/** Straddlers only: validated rightward shift that makes the device cross the seam. */
+	straddleDx?: number;
+	/** zoom only */
+	zoom?: { cropX: number; cropY: number; cropW: number; cropH: number; focusCropped: boolean };
+}
+
+/** Near-edge start for a screen's subject: below (or above, for text-bottom) the reserved text area. */
+function nearStart(t: Typography): number {
+	return t.margin + t.textArea + t.deviceGap;
+}
+
+/**
+ * Fit a zoom crop (natural px) to the card aspect `A` = height / width, centred on the requested
+ * region. An explicit `crop` keeps its full width (the model chose it); a focus-derived band is
+ * zoomed into its centre, up to ZOOM_MAX_MAG× the full-width fit. The height always covers the
+ * requested band when the image allows (else `focusCropped`).
+ */
+function fitCrop(
+	shot: { width: number; height: number },
+	req: { x: number; y: number; w: number; h: number },
+	A: number,
+	explicit: boolean
+): { cropX: number; cropY: number; cropW: number; cropH: number; focusCropped: boolean } {
+	const minW = explicit ? req.w : shot.width / ZOOM_MAX_MAG;
+	let w = Math.min(shot.width, Math.max(minW, req.h / A));
+	let h = w * A;
+	if (h > shot.height) {
+		h = shot.height;
+		w = h / A;
+	}
+	const focusCropped = h < req.h - 0.5 || (explicit && w < req.w - 0.5);
+	const cx = req.x + req.w / 2;
+	const cy = req.y + req.h / 2;
+	const cropX = Math.min(Math.max(0, cx - w / 2), shot.width - w);
+	const cropY = Math.min(Math.max(0, cy - h / 2), shot.height - h);
+	return { cropX, cropY, cropW: w, cropH: h, focusCropped };
+}
+
+const HORIZONTAL_EPS = 1e-9;
+/** A tilted device may shrink to this × its straight scale to keep its margins; else the tilt is reduced. */
+const TILT_MIN_SCALE = 0.8;
+
+/**
+ * The horizontal no-tangent + focus rules for one pose: the subject's VISIBLE extent keeps
+ * `sideMargin`·W from both side edges (the right edge is waived for a deliberate straddle), and
+ * every focus band's rotated corners stay `focusSideSafe`·W inside the edges.
+ */
+function horizontalOk(
+	subject: Subject,
+	pose: { cx: number; cy: number; scale: number; angle: number },
+	W: number,
+	H: number,
+	focuses: FocusBand[],
+	straddleRight = false
+): boolean {
+	const eps = HORIZONTAL_EPS * W;
+	const ext = visibleXExtent(subject, pose, H);
+	if (ext) {
+		const m = NO_TANGENT.sideMargin * W;
+		if (ext.min < m - eps) return false;
+		if (!straddleRight && ext.max > W - m + eps) return false;
+	}
+	const fs = NO_TANGENT.focusSideSafe * W;
+	return focuses.every((f) => {
+		const fx = focusXExtent(subject, f, pose);
+		return fx.min >= fs - eps && fx.max <= W - fs + eps;
+	});
+}
+
+/**
+ * Rightward shift for a panorama straddle: the visible device crosses the seam by STRADDLE_OVERLAP
+ * of its visible width, limited so every focus band stays `focusSideSafe`·W inside the seam. Null
+ * when that leaves less than a decisive STRADDLE_MIN crossing (or would move the device left).
+ */
+function straddleShift(
+	subject: Subject,
+	pose: { cx: number; cy: number; scale: number; angle: number },
+	W: number,
+	H: number,
+	focuses: FocusBand[]
+): number | null {
+	const ext = visibleXExtent(subject, pose, H);
+	if (!ext) return null;
+	const visW = ext.max - ext.min;
+	let dx = W + STRADDLE_OVERLAP * visW - ext.max;
+	for (const f of focuses) dx = Math.min(dx, W * (1 - NO_TANGENT.focusSideSafe) - focusXExtent(subject, f, pose).max);
+	const overlap = ext.max + dx - W;
+	return dx > 0 && overlap >= STRADDLE_MIN * visW ? dx : null;
+}
+
+const screensOf = (members: ResolvedScreen[]) => members.map((m) => m.index + 1).join(', ');
+
+/** The copy is the cause: the device gets < `minScale` of what it would get with no copy at all. */
+const copyTooLong = (members: ResolvedScreen[], W: number, H: number) =>
+	new Error(
+		`copy too long for this canvas (${W}×${H}, screen ${screensOf(members)}): the text leaves the device ` +
+			`less than ${Math.round(NO_TANGENT.minScale * 100)}% of the room it gets with no copy — cut the subheadline or headline`
+	);
+
+/** The canvas is the cause: even with no copy the subject can't reach a usable size. */
+const canvasMismatch = (members: ResolvedScreen[], W: number, H: number, what: string, pct: number) =>
+	new Error(
+		`${what} doesn't fit a ${W}×${H} canvas (screen ${screensOf(members)}): even with no copy it renders at only ` +
+			`${Math.round(pct * 100)}% of its target width — use the device's own canvas (omit canvasWidth/canvasHeight) or another device`
+	);
+
+/** Below this × its target width even with NO copy, the canvas (not the copy) is the problem. */
+const MIN_EMPTY_COPY_FIT = 0.3;
+
+/**
+ * Pose of every screen in a group (they share scale, baseline and far-edge treatment).
+ * Vertical: `solveVertical` (no tangent, focus visible). Horizontal: the pose must pass
+ * `horizontalOk` for every member; if the tilt makes it too wide, the scale is capped (by at most
+ * TILT_MIN_SCALE), then the tilt is reduced in quarter steps down to 0 (a straight device ≤ 90% W
+ * always fits), with a `tilt-reduced` warning. Zoom cards follow the same ladder, keeping their
+ * aspect. Throws `copyTooLong` when the copy leaves < minScale of the no-copy fit, and
+ * `canvasMismatch` when even the no-copy fit is unusable (N1).
+ */
+function placeGroup(
+	members: ResolvedScreen[],
+	bleed: BleedPreference,
+	warnings: ComposeWarning[],
+	/** Every member is a requested panorama straddler: the right side margin is waived (it crosses the seam). */
+	straddleRight = false
+): Map<number, Placement> {
+	const out = new Map<number, Placement>();
+	const first = members[0];
+	const { W, H, typo, layout, presentation, tilt } = first;
+	const spec = LAYOUTS[layout] ?? LAYOUTS['text-top'];
+	const farEdge = layout === 'text-bottom' ? 'top' : 'bottom';
+	const near = nearStart(typo);
+	const reduced = (to: number) => {
+		if (to === tilt) return;
+		warnings.push({
+			screen: first.index,
+			code: 'tilt-reduced',
+			message: `screen ${members.map((m) => m.index + 1).join(', ')}: tilt reduced from ${tilt}° to ${Math.round(to * 10) / 10}° so the device and its focus band keep their side margins`
+		});
+	};
+
+	if (presentation === 'zoom') {
+		// One card box for the group. Straight, it spans the full remaining height (clear of the far
+		// edge by the margin) at ZOOM_WIDTH·W, never flatter than ZOOM_MIN_ASPECT. That ASPECT is kept at
+		// every tilt: a tilted card scales down (≤ TILT_MIN_SCALE) until its rotated bounding box fits
+		// the remaining height and the 90%-W side margins; beyond that the tilt is reduced (quarter
+		// steps, `tilt-reduced`), and a straight card always fits.
+		const avail = H * (1 - NO_TANGENT.clearGap) - near;
+		const availEmpty = H * (1 - NO_TANGENT.clearGap) - (typo.margin + typo.deviceGap);
+		if (!(avail > 0) || avail < NO_TANGENT.minScale * availEmpty) throw copyTooLong(members, W, H);
+		let baseW = ZOOM_WIDTH * W;
+		const baseH = avail;
+		if (baseH < baseW * ZOOM_MIN_ASPECT) {
+			baseW = baseH / ZOOM_MIN_ASPECT;
+		}
+		const aspect = baseH / baseW;
+		const maxBoxWidth = (1 - 2 * NO_TANGENT.sideMargin) * W;
+		const fitAt = (angle: number) => {
+			const rad = (angle * Math.PI) / 180;
+			const sin = Math.abs(Math.sin(rad));
+			const cos = Math.abs(Math.cos(rad));
+			const k = Math.min(1, maxBoxWidth / (baseW * (cos + aspect * sin)), avail / (baseW * (sin + aspect * cos)));
+			return { k, boxW: k * baseW, boxH: k * baseW * aspect };
+		};
+		let angleUsed = 0;
+		let fit = fitAt(0);
+		for (const angle of tilt === 0 ? [0] : [tilt, tilt * 0.75, tilt * 0.5, tilt * 0.25, 0]) {
+			const f = fitAt(angle);
+			if (angle === 0 || f.k >= TILT_MIN_SCALE - 1e-9) {
+				angleUsed = angle;
+				fit = f;
+				break;
+			}
+		}
+		reduced(angleUsed);
+		const tiltUsed = angleUsed;
+		const { boxW, boxH } = fit;
+		const box = rotatedBox(boxW, boxH, tiltUsed);
+		for (const r of members) {
+			const shot = r.plan.screenshot;
+			const focus = normalizeFocus(r.plan.focus);
+			const crop = r.plan.crop;
+			const req = crop
+				? { x: clamp01(crop.x) * shot.width, y: clamp01(crop.y) * shot.height, w: Math.max(1, clamp01(crop.w) * shot.width), h: Math.max(1, clamp01(crop.h) * shot.height) }
+				: focus
+					? { x: 0, y: focus.top * shot.height, w: shot.width, h: (focus.bottom - focus.top) * shot.height }
+					: { x: 0, y: 0, w: shot.width, h: Math.min(shot.height, shot.width * (boxH / boxW)) };
+			const zoom = fitCrop(shot, req, boxH / boxW, !!crop);
+			const scale = boxW / zoom.cropW;
+			const nearEdge = near;
+			const cy = farEdge === 'bottom' ? nearEdge + box.height / 2 : H - nearEdge - box.height / 2;
+			const overshoot = nearEdge + box.height - H;
+			out.set(r.index, {
+				cx: W / 2,
+				cy,
+				scale,
+				angle: tiltUsed,
+				boxWidth: box.width,
+				boxHeight: box.height,
+				vertical: { scale, near: nearEdge, overshoot, mode: 'clear', bleedFraction: overshoot / box.height, reason: 'zoom card clears the edge' },
+				subject: { width: zoom.cropW, height: zoom.cropH, screen: { x: 0, y: 0, width: zoom.cropW, height: zoom.cropH } },
+				zoom
+			});
 		}
+		return out;
+	}
 
-		// One device layer; the screenshot rides on it as `fabricData.screenshot` and the editor
-		// places + clips it under the frame on import (see DeviceScreenshotJSON).
-		const frame = makeDeviceFrameLayer({
-			deviceId: screen.deviceId,
-			screenshotUrl: screen.screenshot.url,
-			screenshotWidth: screen.screenshot.width,
-			screenshotHeight: screen.screenshot.height,
+	const subject = subjectFor(first);
+	const targetWidth = Math.min(spec.deviceWidth * (presentation === 'frameless' ? FRAMELESS_WIDTH : 1), NO_TANGENT.maxWidth);
+	const targetScale = (targetWidth * W) / subject.width;
+	// Every member's focus band is honoured by the shared pose (the most restrictive one decides).
+	const focuses = members.map((r) => normalizeFocus(r.plan.focus)).filter((f): f is FocusBand => !!f);
+	const solve = (angle: number, scaleCap?: number, nearOverride?: number) => {
+		const box = rotatedBox(subject.width, subject.height, angle);
+		const reaches = focuses.map((f) => focusReach(subject, f, angle, farEdge));
+		const vertical = solveVertical({
 			canvasWidth: W,
 			canvasHeight: H,
-			centerX: W / 2,
-			centerY,
-			scale
+			near: nearOverride ?? near,
+			minNear: spec.minDeviceTop * H,
+			baseWidth: subject.width,
+			boxHeight: box.height,
+			targetWidth,
+			maxBleed: spec.maxBleed,
+			focusReach: reaches.length ? Math.max(...reaches) : null,
+			bleed,
+			preferBleed: angle !== 0,
+			scaleCap
 		});
+		const s = vertical.scale;
+		const cy = farEdge === 'bottom' ? vertical.near + (s * box.height) / 2 : H - vertical.near - (s * box.height) / 2;
+		return { vertical, box, cy, angle };
+	};
 
-		// Center origin (editor convention): left/top are the box CENTER.
-		const headlineColor = screen.headlineColor ?? '#ffffff';
-		const headline = makeTextLayer({
-			text: screen.headline,
-			left: W / 2,
-			top: blockTop + block.headlineHeight / 2,
-			width: textWidth,
-			fontSize: block.headlineSize,
-			fontWeight: '800',
-			lineHeight: HEADLINE_LINE_HEIGHT,
-			fill: headlineColor,
-			textAlign: 'center',
-			name: 'Headline',
-			templateRole: 'editable',
-			templateKey: 'headline'
+	// L7 / N1: the room gate is relative to what the SAME subject gets on this canvas with NO copy
+	// (height-limited on landscape canvases), so a tall device on a squat canvas isn't blamed on the
+	// copy. Too small even with no copy ⇒ the canvas/device aspect is the problem.
+	const straight = solve(0);
+	const empty = solve(0, undefined, typo.margin + typo.deviceGap).vertical.scale;
+	if (!(empty >= MIN_EMPTY_COPY_FIT * targetScale - 1e-9)) {
+		throw canvasMismatch(members, W, H, presentation === 'device' ? `device ${first.plan.deviceId}` : 'this screenshot', empty / targetScale);
+	}
+	const minScale = NO_TANGENT.minScale * empty;
+	if (!(straight.vertical.scale >= minScale - 1e-9)) throw copyTooLong(members, W, H);
+
+	// A tilt may cost at most TILT_MIN_SCALE of the straight size; beyond that the tilt is reduced
+	// (in quarter steps down to 0) rather than shrinking the device further.
+	const tiltFloor = Math.max(minScale, TILT_MIN_SCALE * straight.vertical.scale);
+	// Search: tilt candidates (reduced in quarter steps), each with a shrinking scale cap. A straddler
+	// is judged AFTER its seam shift (right margin waived; left margin + focus vs seam checked); if no
+	// straddling pose exists it is placed as a normal screen (the caller then skips the straddle).
+	const search = (asStraddle: boolean) => {
+		for (const angle of tilt === 0 ? [0] : [tilt, tilt * 0.75, tilt * 0.5, tilt * 0.25, 0]) {
+			const floor = angle === 0 ? minScale : tiltFloor;
+			let cap: number | undefined;
+			for (let i = 0; i < 400; i++) {
+				const sol = solve(angle, cap);
+				const pose = { cx: W / 2, cy: sol.cy, scale: sol.vertical.scale, angle };
+				if (sol.vertical.scale >= floor - 1e-9) {
+					if (!asStraddle && horizontalOk(subject, pose, W, H, focuses)) return { sol, dx: undefined as number | undefined };
+					if (asStraddle) {
+						const dx = straddleShift(subject, pose, W, H, focuses);
+						if (dx != null && horizontalOk(subject, { ...pose, cx: pose.cx + dx }, W, H, focuses, true)) return { sol, dx };
+					}
+				}
+				const next = sol.vertical.scale * 0.985;
+				if (next < floor) break;
+				cap = next;
+			}
+		}
+		return null;
+	};
+	// A straight, centred device at ≤ 90% W always passes; `straight` is the defensive fallback.
+	const found = (straddleRight ? search(true) : null) ?? search(false) ?? { sol: straight, dx: undefined };
+	const chosen = found.sol;
+	reduced(chosen.angle);
+	const s = chosen.vertical.scale;
+	for (const r of members) {
+		out.set(r.index, {
+			cx: W / 2,
+			cy: chosen.cy,
+			scale: s,
+			angle: chosen.angle,
+			boxWidth: s * chosen.box.width,
+			boxHeight: s * chosen.box.height,
+			vertical: chosen.vertical,
+			subject,
+			straddleDx: found.dx
 		});
+	}
+	return out;
+}
+
+function shadowFor(W: number, scale: number) {
+	// Fabric scales shadow blur/offset by the object's scale (the editor's shadow controls use the
+	// same convention), so express them in the image's own units.
+	return { color: SHADOW.color, blur: (SHADOW.blur * W) / scale, offsetX: 0, offsetY: (SHADOW.offsetY * W) / scale };
+}
+
+/** Frameless / zoom subject: the uploaded screenshot as a plain image layer, rounded + shadowed. */
+function makeScreenshotImageLayer(r: ResolvedScreen, p: Placement): LayerJSON {
+	const id = generateLayerId();
+	const shot = r.plan.screenshot;
+	const zoom = p.zoom;
+	const width = zoom ? zoom.cropW : shot.width;
+	const height = zoom ? zoom.cropH : shot.height;
+	const radius = zoom ? ZOOM_RADIUS * r.W : FRAMELESS_RADIUS * width * p.scale;
+	const fabricData: Record<string, unknown> = {
+		type: 'image',
+		src: shot.url,
+		crossOrigin: 'anonymous',
+		left: p.cx,
+		top: p.cy,
+		width,
+		height,
+		scaleX: p.scale,
+		scaleY: p.scale,
+		originX: 'center',
+		originY: 'center',
+		// Rounded corners in the image's local (unscaled) space — same shape the editor's corner
+		// radius control writes (`imageCornerRadius` is in canvas units).
+		clipPath: {
+			type: 'Rect',
+			left: 0,
+			top: 0,
+			width,
+			height,
+			rx: radius / p.scale,
+			ry: radius / p.scale,
+			originX: 'center',
+			originY: 'center'
+		},
+		imageCornerRadius: radius,
+		shadow: shadowFor(r.W, p.scale),
+		layerId: id,
+		layerType: 'image'
+	};
+	if (zoom) {
+		fabricData.cropX = zoom.cropX;
+		fabricData.cropY = zoom.cropY;
+	}
+	if (p.angle) fabricData.angle = p.angle;
+	return {
+		id,
+		name: zoom ? 'Screenshot (zoom)' : 'Screenshot',
+		type: 'image',
+		visible: true,
+		locked: false,
+		fabricData
+	};
+}
 
-		// BOTTOM → TOP (canvas add order): device -> headline -> subheadline.
-		const layers: LayerJSON[] = [frame, headline];
+function makeSubjectLayer(r: ResolvedScreen, p: Placement, cx = p.cx, name?: string): LayerJSON {
+	if (r.presentation === 'device') {
+		// One device layer; the screenshot rides on it as `fabricData.screenshot` and the editor
+		// places + clips it under the frame on import (see DeviceScreenshotJSON).
+		return makeDeviceFrameLayer({
+			deviceId: r.plan.deviceId,
+			screenshotUrl: r.plan.screenshot.url,
+			screenshotWidth: r.plan.screenshot.width,
+			screenshotHeight: r.plan.screenshot.height,
+			canvasWidth: r.W,
+			canvasHeight: r.H,
+			centerX: cx,
+			centerY: p.cy,
+			scale: p.scale,
+			angle: p.angle,
+			name
+		});
+	}
+	const layer = makeScreenshotImageLayer(r, p);
+	(layer.fabricData as Record<string, unknown>).left = cx;
+	if (name) layer.name = name;
+	return layer;
+}
+
+/** Canvas corners of a screen's focus band for a given pose (null when no focus is marked). */
+function focusPolygon(r: ResolvedScreen, p: Placement, cx: number) {
+	const focus = normalizeFocus(r.plan.focus);
+	if (!focus || p.zoom) return null;
+	return focusCorners(p.subject, focus).map((pt) => subjectPointToCanvas(p.subject, pt, { cx, cy: p.cy, scale: p.scale, angle: p.angle }));
+}
+
+interface TextRects {
+	badge?: { left: number; top: number; right: number; bottom: number };
+	headline: { left: number; top: number; right: number; bottom: number };
+	sub?: { left: number; top: number; right: number; bottom: number };
+}
+
+function validateSpans(plan: ComposePlan, dims: Array<{ W: number; H: number }>): number[][] {
+	const spans = plan.style?.panorama?.spans ?? [];
+	const seen = new Set<number>();
+	for (const span of spans) {
+		if (!Array.isArray(span) || span.length < 2) throw new Error('panorama span must list at least 2 screens');
+		span.forEach((idx, k) => {
+			if (!Number.isInteger(idx) || idx < 0 || idx >= plan.screens.length) throw new Error(`panorama span index ${idx} is out of range`);
+			if (k > 0 && idx !== span[k - 1] + 1) throw new Error('panorama span screens must be adjacent and ascending');
+			if (seen.has(idx)) throw new Error(`screen ${idx} is in more than one panorama span`);
+			seen.add(idx);
+			if (dims[idx].W !== dims[span[0]].W || dims[idx].H !== dims[span[0]].H) {
+				throw new Error('panorama span screens must share one canvas size');
+			}
+		});
+	}
+	const straddle = plan.style?.panorama?.straddle;
+	if (Array.isArray(straddle)) {
+		for (const idx of straddle) {
+			if (!spans.some((span) => span[0] === idx)) throw new Error(`panorama straddle ${idx} is not the first screen of a span`);
+		}
+	}
+	return spans;
+}
+
+/**
+ * Two-pass SET layout: measure every text block → one type size + a text area reserved for the
+ * tallest block (per canvas size) → one subject scale/baseline per group (canvas, presentation,
+ * subject, layout, tilt) → the no-tangent bleed rule (respecting `focus`) → per-screen layers.
+ * Copy length never moves or resizes anything; copy-rule violations come back as `report.warnings`.
+ */
+export function composeSet(plan: ComposePlan): { template: Template; report: ComposeReport } {
+	const style = plan.style ?? {};
+	const warnings: ComposeWarning[] = [];
+	const bleedPref: BleedPreference = (COMPOSE_BLEEDS as readonly string[]).includes(style.bleed ?? '') ? style.bleed! : 'auto';
+	const font = style.font && COMPOSE_FONTS.includes(style.font) ? style.font : 'Inter';
+	const tiltScreens = new Set(style.tiltScreens ?? []);
+
+	// Per-screen canvas dims: honor explicit plan-level dims (backward compatible), else derive from
+	// the screen's device class so a mixed-device plan gets the correct aspect per screen.
+	const explicit = plan.canvasWidth != null || plan.canvasHeight != null;
+	const dims = plan.screens.map((screen) => {
+		if (!getDeviceFrame(screen.deviceId)) throw new Error(`Unknown device: ${screen.deviceId}`);
+		const { width, height } = explicit
+			? { width: plan.canvasWidth ?? 280, height: plan.canvasHeight ?? 600 }
+			: canvasDimsForDevice(screen.deviceId);
+		return { W: width, H: height };
+	});
+	const spans = validateSpans(plan, dims);
+	const spanOf = new Map<number, { span: number[]; k: number }>();
+	for (const span of spans) span.forEach((idx, k) => spanOf.set(idx, { span, k }));
+
+	// Pass 1: set typography per canvas size (tallest text block wins).
+	const typoByDims = new Map<string, Typography>();
+	const dimsKey = (d: { W: number; H: number }) => `${d.W}x${d.H}`;
+	plan.screens.forEach((_, i) => {
+		const key = dimsKey(dims[i]);
+		if (typoByDims.has(key)) return;
+		const { W, H } = dims[i];
+		const unit = Math.min(W, H * TYPE_UNIT_HEIGHT_CAP);
+		const headlineSize = unit * HEADLINE_SIZE;
+		const hasBadge = plan.screens.some((s, j) => dimsKey(dims[j]) === key && !!s.badge?.trim());
+		const badgeFont = headlineSize * BADGE_FONT;
+		typoByDims.set(key, {
+			W,
+			H,
+			unit,
+			headlineSize,
+			subSize: headlineSize * SUBHEADLINE_RATIO,
+			textWidth: W * TEXT_WIDTH,
+			margin: H * EDGE_MARGIN,
+			deviceGap: unit * DEVICE_GAP,
+			badgeFont,
+			font,
+			badgeRow: hasBadge ? badgeFont * BADGE_HEIGHT + headlineSize * BADGE_GAP : 0,
+			textArea: 0
+		});
+	});
+
+	const resolved: ResolvedScreen[] = plan.screens.map((screen, i) => {
+		const typo = typoByDims.get(dimsKey(dims[i]))!;
+		const block = measureTextBlock(screen, typo);
+		typo.textArea = Math.max(typo.textArea, block.height);
+		const presentation: ComposePresentation = (COMPOSE_PRESENTATIONS as readonly string[]).includes(screen.presentation ?? '')
+			? screen.presentation!
+			: (COMPOSE_PRESENTATIONS as readonly string[]).includes(style.presentation ?? '')
+				? style.presentation!
+				: 'device';
+		let layout: ComposeLayout = screen.layout && LAYOUTS[screen.layout] ? screen.layout : 'text-top';
+		if (presentation === 'zoom' && layout === 'device-bleed') layout = 'text-top';
+		const rawTilt = typeof screen.tilt === 'number' ? screen.tilt : tiltScreens.has(i) ? (style.tilt ?? 0) : 0;
+		const tilt = Number.isFinite(rawTilt) ? Math.max(-30, Math.min(30, rawTilt)) : 0;
+		const fromPalette = screen.background ? null : paletteBackground(style.palette, i);
+		const background = screen.background ?? fromPalette ?? { type: 'solid', color: '#1F2937' };
+		const backgroundFromStyle = !screen.background;
+		const subjectKey =
+			presentation === 'device'
+				? screen.deviceId
+				: presentation === 'frameless'
+					? `shot:${screen.screenshot.width}x${screen.screenshot.height}`
+					: 'card';
+		const group = `${dims[i].W}x${dims[i].H}|${presentation}|${subjectKey}|${layout}|tilt:${tilt}`;
+		return {
+			index: i,
+			plan: screen,
+			W: dims[i].W,
+			H: dims[i].H,
+			layout,
+			presentation,
+			tilt,
+			background,
+			backgroundFromStyle,
+			typo,
+			block,
+			group
+		};
+	});
+
+	// Requested straddlers: the first screen of a span, per `panorama.straddle` (never zoom cards).
+	// They get their own group (their pose is judged after the seam shift).
+	const straddleSpec = style.panorama?.straddle;
+	const wantsStraddle = new Set(
+		straddleSpec
+			? spans.map((span) => span[0]).filter((i) => (Array.isArray(straddleSpec) ? straddleSpec.includes(i) : true) && resolved[i].presentation !== 'zoom')
+			: []
+	);
+	for (const i of wantsStraddle) resolved[i].group += '|straddle';
+
+	// Pass 2: one pose per group.
+	const groups = new Map<string, ResolvedScreen[]>();
+	for (const r of resolved) groups.set(r.group, [...(groups.get(r.group) ?? []), r]);
+	const placements = new Map<number, Placement>();
+	for (const members of groups.values()) {
+		const asStraddle = members.every((m) => wantsStraddle.has(m.index));
+		for (const [i, p] of placeGroup(members, bleedPref, warnings, asStraddle)) placements.set(i, p);
+	}
+
+	// Panorama: straddling devices (first screen of a span) cross into the next screen.
+	const straddle = new Map<number, { cx: number; into: number }>();
+	if (wantsStraddle.size) {
+		for (const span of spans) {
+			const i = span[0];
+			if (!wantsStraddle.has(i)) continue;
+			const r = resolved[i];
+			const p = placements.get(i)!;
+			if (r.presentation === 'zoom') continue;
+			const W = r.W;
+			// placeGroup found (or failed to find) a pose that straddles within the side / seam rules.
+			const dx = p.straddleDx;
+			const focus = normalizeFocus(r.plan.focus);
+			if (dx == null) {
+				warnings.push({
+					screen: i,
+					code: 'straddle-skipped',
+					message: `screen ${i + 1}: device kept inside its screen — crossing the seam would put its focus band across it (or break the side margin)`
+				});
+				continue;
+			}
+			if (!focus) {
+				warnings.push({
+					screen: i,
+					code: 'panorama-seam',
+					message: `screen ${i + 1}: the device crosses the seam into screen ${i + 2} but has no \`focus\` band marked — mark one so the selling UI provably stays on screen ${i + 1}`
+				});
+			}
+			straddle.set(i, { cx: W / 2 + dx, into: span[1] });
+		}
+	}
+
+	// Span fills (validated up front, so a bad span background fails before any layer is built).
+	const spanFills = new Map<number, SpanFill>();
+	for (const span of spans) {
+		const r0 = resolved[span[0]];
+		spanFills.set(span[0], spanFillFor(r0.background, span[0], span.length, r0.W, r0.H));
+	}
+	/** Vertical band of a screen's reserved text block (with a small breathing gap). */
+	const textBand = (r: ResolvedScreen) => {
+		const top = r.layout === 'text-bottom' ? r.H - r.typo.margin - r.typo.textArea : r.typo.margin;
+		const gap = ORB_TEXT_GAP * r.H;
+		return { top: top - gap, bottom: top + r.typo.textArea + gap };
+	};
+	/**
+	 * The orb on seam `seam` of a span: centred on ORB_Y·H with ORB_RADIUS·W, but moved/shrunk so it
+	 * never overlaps either neighbour's text block (small landscape canvases); null when there's no room.
+	 */
+	const orbFor = (span: number[], seam: number): { cy: number; r: number } | null => {
+		const a = resolved[span[seam - 1]];
+		const b = resolved[span[seam]];
+		const H = a.H;
+		const blocks = [textBand(a), textBand(b)].sort((x, y) => x.top - y.top);
+		const free: Array<{ lo: number; hi: number }> = [];
+		let cursor = 0;
+		for (const t of blocks) {
+			if (t.top > cursor) free.push({ lo: cursor, hi: t.top });
+			cursor = Math.max(cursor, t.bottom);
+		}
+		if (cursor < H) free.push({ lo: cursor, hi: H });
+		const want = ORB_Y * H;
+		const pick = free.find((f) => f.lo <= want && want <= f.hi) ?? free.sort((x, y) => y.hi - y.lo - (x.hi - x.lo))[0];
+		if (!pick) return null;
+		// The orb may run off the canvas edge (it's decoration), but never into a text block.
+		const lo = pick.lo === 0 ? -Infinity : pick.lo;
+		const hi = pick.hi === H ? Infinity : pick.hi;
+		const r = Math.min(ORB_RADIUS * a.W, (hi - lo) / 2);
+		if (!(r >= ORB_MIN_RADIUS * a.W)) return null;
+		const cy = Math.min(Math.max(want, lo + r), hi - r);
+		return { cy, r };
+	};
+
+	// Pass 3: layers per screen.
+	const metrics: ComposeScreenMetrics[] = [];
+	const textRectsByScreen = new Map<number, TextRects>();
+	const screens = resolved.map((r) => {
+		const { W, H, typo, block, plan: screen } = r;
+		const p = placements.get(r.index)!;
+		const layers: LayerJSON[] = [];
+		let background = r.background;
+
+		// Panorama background + seam decoration (BOTTOM of the stack).
+		const inSpan = spanOf.get(r.index);
+		if (inSpan) {
+			const { span, k } = inSpan;
+			const N = span.length;
+			// The span's FIRST screen's (already resolved) background runs across the whole span.
+			const fill = spanFills.get(span[0])!;
+			background = { type: 'solid', color: fill.kind === 'solid' ? fill.color : fill.stops[0].color };
+			const bg = makeShapeLayer({
+				shape: 'rectangle',
+				left: (N * W) / 2 - k * W,
+				top: H / 2,
+				width: N * W,
+				height: H,
+				name: `Panorama background (${k + 1}/${N})`,
+				locked: true
+			});
+			Object.assign(bg.fabricData as Record<string, unknown>, {
+				fill:
+					fill.kind === 'solid'
+						? fill.color
+						: {
+								type: 'linear',
+								gradientUnits: 'pixels',
+								coords: { ...fill.coords },
+								colorStops: fill.stops.map((s) => ({ offset: s.offset, color: s.color })),
+								offsetX: 0,
+								offsetY: 0
+							},
+				selectable: false,
+				evented: false
+			});
+			layers.push(bg);
+			if ((style.panorama?.decoration ?? 'orbs') === 'orbs') {
+				// A soft orb centred on each seam touching this screen, kept clear of both text blocks.
+				for (let seam = 1; seam < N; seam++) {
+					if (seam !== k && seam !== k + 1) continue;
+					const orb = orbFor(span, seam);
+					if (!orb) continue;
+					layers.push(
+						makeShapeLayer({
+							shape: 'circle',
+							left: seam * W - k * W,
+							top: orb.cy,
+							radius: orb.r,
+							fill: 'rgba(255,255,255,0.14)',
+							name: 'Panorama orb'
+						})
+					);
+				}
+			}
+		}
+
+		// A device straddling in from the previous screen sits under this screen's own subject.
+		for (const [from, s] of straddle) {
+			if (s.into !== r.index) continue;
+			const fr = resolved[from];
+			const fp = placements.get(from)!;
+			const cont = makeSubjectLayer(fr, fp, s.cx - W, `${getDeviceFrame(fr.plan.deviceId)?.name ?? 'Screenshot'} (continued)`);
+			layers.push(cont);
+		}
+
+		const cx = straddle.get(r.index)?.cx ?? p.cx;
+		layers.push(makeSubjectLayer(r, p, cx));
+
+		// Text block: badge row → headline → subheadline, anchored to the reserved text area.
+		const areaTop = r.layout === 'text-bottom' ? H - typo.margin - typo.textArea : typo.margin;
+		const rects: TextRects = {
+			headline: { left: (W - typo.textWidth) / 2, top: 0, right: (W + typo.textWidth) / 2, bottom: 0 }
+		};
+		// Auto text colour from the background ACTUALLY behind the text block (after the panorama
+		// swap): sample the span gradient / screen background over the block. An explicit
+		// headlineColor wins; explicit (non-palette) backgrounds outside a span keep the white default.
+		const blockBottom = areaTop + typo.badgeRow + block.headlineHeight + block.gap + block.subHeight;
+		const samples: string[] = [];
+		for (const fx of [0.1, 0.5, 0.9]) {
+			for (const fy of [0, 0.5, 1]) {
+				const x = fx * W;
+				const y = areaTop + fy * (blockBottom - areaTop);
+				samples.push(inSpan ? samplePanorama(spanFills.get(inSpan.span[0])!, inSpan.k, W, x, y) : sampleBackground(r.background, W, H, x, y));
+			}
+		}
+		const headlineColor = screen.headlineColor ?? (inSpan || r.backgroundFromStyle ? readableTextOn(samples) : '#ffffff');
+		if (screen.badge?.trim()) {
+			const text = screen.badge.trim();
+			if (text.length > BADGE_MAX_CHARS) {
+				warnings.push({ screen: r.index, code: 'badge-long', message: `screen ${r.index + 1}: badge "${text}" is long — keep it to 1–3 words` });
+			}
+			const fontSize = typo.badgeFont;
+			const pillH = fontSize * BADGE_HEIGHT;
+			const pillW = Math.min(typo.textWidth, estimateTextWidth(text, fontSize, typo.font) + 2 * BADGE_PAD_X * fontSize);
+			const cy = areaTop + pillH / 2;
+			const pill = makeShapeLayer({
+				shape: 'rectangle',
+				left: W / 2,
+				top: cy,
+				width: pillW,
+				height: pillH,
+				rx: pillH / 2,
+				ry: pillH / 2,
+				fill: rgba(isHexColor(headlineColor) ? headlineColor : '#ffffff', 0.18),
+				name: 'Badge'
+			});
+			const label = makeTextLayer({
+				text,
+				left: W / 2,
+				top: cy,
+				width: pillW,
+				fontSize,
+				fontFamily: font,
+				fontWeight: '700',
+				lineHeight: 1,
+				fill: headlineColor,
+				textAlign: 'center',
+				name: 'Badge text',
+				templateRole: 'editable',
+				templateKey: 'badge'
+			});
+			layers.push(pill, label);
+			rects.badge = { left: W / 2 - pillW / 2, top: areaTop, right: W / 2 + pillW / 2, bottom: areaTop + pillH };
+		}
+		const headlineTop = areaTop + typo.badgeRow;
+		rects.headline.top = headlineTop;
+		rects.headline.bottom = headlineTop + block.headlineHeight;
+
+		// Center origin (editor convention): left/top are the box CENTER.
+		layers.push(
+			makeTextLayer({
+				text: screen.headline,
+				left: W / 2,
+				top: headlineTop + block.headlineHeight / 2,
+				width: typo.textWidth,
+				fontSize: typo.headlineSize,
+				fontFamily: font,
+				fontWeight: '800',
+				lineHeight: HEADLINE_LINE_HEIGHT,
+				fill: headlineColor,
+				textAlign: 'center',
+				name: 'Headline',
+				templateRole: 'editable',
+				templateKey: 'headline'
+			})
+		);
 
 		if (screen.subheadline?.trim()) {
+			const subTop = headlineTop + block.headlineHeight + block.gap;
 			const sub = makeTextLayer({
 				text: screen.subheadline,
 				left: W / 2,
-				top: blockTop + block.headlineHeight + block.gap + block.subHeight / 2,
-				width: textWidth,
-				fontSize: block.subSize,
+				top: subTop + block.subHeight / 2,
+				width: typo.textWidth,
+				fontSize: typo.subSize,
+				fontFamily: font,
 				fontWeight: '500',
 				lineHeight: SUBHEADLINE_LINE_HEIGHT,
 				fill: screen.subheadlineColor ?? headlineColor,
@@ -244,10 +1317,34 @@ export function composeTemplate(plan: ComposePlan): Template {
 			// in the editor). An explicit subheadlineColor is used as-is.
 			if (!screen.subheadlineColor) (sub.fabricData as Record<string, unknown>).opacity = SUBHEADLINE_OPACITY;
 			layers.push(sub);
+			rects.sub = { left: rects.headline.left, top: subTop, right: rects.headline.right, bottom: subTop + block.subHeight };
 		}
+		textRectsByScreen.set(r.index, rects);
+
+		const top = p.cy - p.boxHeight / 2;
+		const bottom = p.cy + p.boxHeight / 2;
+		const overshoot = r.layout === 'text-bottom' ? -top : bottom - H;
+		metrics.push({
+			index: r.index,
+			presentation: r.presentation,
+			layout: r.layout,
+			group: r.group,
+			scale: p.scale,
+			widthFraction: (p.subject.width * p.scale) / W,
+			top: top / H,
+			bottom: bottom / H,
+			overshoot: overshoot / H,
+			bleedFraction: p.boxHeight > 0 ? overshoot / p.boxHeight : 0,
+			mode: overshoot > 0 ? 'bleed' : 'clear',
+			tangent: inTangentZone(overshoot, p.boxHeight, H),
+			headlineSize: typo.headlineSize / W,
+			headlineTop: headlineTop / H,
+			tilt: p.angle,
+			centerX: cx / W
+		});
 
 		return makeScreen({
-			background: screen.background,
+			background,
 			canvasWidth: W,
 			canvasHeight: H,
 			// Tag the device GROUP (multi-device) so a mixed plan lands as separate sidebar groups in
@@ -257,5 +1354,71 @@ export function composeTemplate(plan: ComposePlan): Template {
 		});
 	});
 
-	return makeTemplate({ name: plan.name, screens, tags: ['generated'] });
+	// Copy + composition lint (warnings, never errors).
+	resolved.forEach((r) => {
+		const words = r.plan.headline.trim().split(/\s+/).filter(Boolean).length;
+		const n = r.index + 1;
+		if (words > COPY_RULES.headlineMaxWords) {
+			warnings.push({ screen: r.index, code: 'headline-words', message: `screen ${n}: headline has ${words} words (aim for 3–5) — cut, don't shrink` });
+		}
+		if (r.block.headlineLines > COPY_RULES.headlineMaxLines) {
+			warnings.push({
+				screen: r.index,
+				code: 'headline-lines',
+				message: `screen ${n}: headline wraps to ~${r.block.headlineLines} lines at the set size (max 2) — it grows the text area for EVERY screen`
+			});
+		}
+		if (r.block.subLines > COPY_RULES.subheadlineMaxLines) {
+			warnings.push({
+				screen: r.index,
+				code: 'subheadline-lines',
+				message: `screen ${n}: subheadline wraps to ~${r.block.subLines} lines (max 1) — shorten it or drop it`
+			});
+		}
+		const p = placements.get(r.index)!;
+		if (p.zoom?.focusCropped) {
+			warnings.push({ screen: r.index, code: 'zoom-focus-cropped', message: `screen ${n}: the zoom card can't show the whole focus band — mark a tighter \`crop\`` });
+		}
+	});
+	if (straddle.size > MAX_STRADDLES) {
+		warnings.push({
+			code: 'panorama-straddle-count',
+			message: `${straddle.size} devices cross a seam — keep it to ${MAX_STRADDLES} per set (usually the hero) so the set stays calm`
+		});
+	}
+	const tilted = resolved.filter((r) => r.tilt !== 0).length;
+	if (tilted > COPY_RULES.maxTiltedScreens) {
+		warnings.push({ code: 'tilt-count', message: `${tilted} screens are tilted — rotation is an accent: use it on at most ${COPY_RULES.maxTiltedScreens}` });
+	}
+	// Seam rule: nothing crossing a seam may touch a headline, and no focus band may cross a seam.
+	for (const [from, s] of straddle) {
+		const fr = resolved[from];
+		const fp = placements.get(from)!;
+		for (const [screenIdx, cx] of [
+			[from, s.cx],
+			[s.into, s.cx - fr.W]
+		] as const) {
+			const box = { left: cx - fp.boxWidth / 2, right: cx + fp.boxWidth / 2, top: fp.cy - fp.boxHeight / 2, bottom: fp.cy + fp.boxHeight / 2 };
+			const t = textRectsByScreen.get(screenIdx)!;
+			if ([t.headline, t.sub, t.badge].some((rect) => rect && rectsOverlap(rect, box))) {
+				warnings.push({ screen: screenIdx, code: 'panorama-seam', message: `screen ${screenIdx + 1}: the straddling device overlaps the text` });
+			}
+		}
+		const poly = focusPolygon(fr, fp, s.cx);
+		if (poly && Math.max(...poly.map((pt) => pt.x)) > fr.W) {
+			warnings.push({ screen: from, code: 'panorama-seam', message: `screen ${from + 1}: the seam crosses the focus band` });
+		}
+	}
+
+	metrics.sort((a, b) => a.index - b.index);
+	return { template: makeTemplate({ name: plan.name, screens, tags: ['generated'] }), report: { warnings, screens: metrics } };
+}
+
+/**
+ * Deterministically assemble a Template from a plan (see `composeSet` for the set-wide layout rules
+ * and the lint report). Text layers are marked editable so the user can tweak them in the editor.
+ * Claude decides the plan (benefit, copy, device, palette, layout, style); this turns it into valid DSL.
+ */
+export function composeTemplate(plan: ComposePlan): Template {
+	return composeSet(plan).template;
 }