@appshoteditor/shot-dsl 0.4.0 → 0.5.1

package/src/variants.ts

@@ -1,26 +1,42 @@
-import { canvasDimsForDevice, type ComposePlan, type ComposeScreenPlan, type ComposeStyle } from './compose';
+import {
+	canvasDimsForDevice,
+	type ComposeHero,
+	type ComposeMascot,
+	type ComposePalette,
+	type ComposePlan,
+	type ComposeScreenPlan,
+	type ComposeStyle
+} from './compose';
+import { isHexColor } from './color';
+import type { Motif } from './decor';
 
 /**
- * Three DISTINCT concepts from one plan — Product Page Optimization test candidates, not tweaks:
- * - **A Framed**: device mockups, straight, one shared layout.
- * - **B Frameless**: bare rounded screenshots; screens with a `crop` (or a tight `focus` band) become
- *   magnified zoom cards of that UI.
- * - **C Panorama**: adjacent pairs share one continuous background + seam orbs; only the tilted hero
- *   (screen 1) straddles its seam — one crossing per set, rotation stays an accent.
+ * Three DISTINCT art directions from one plan — Product Page Optimization test candidates, not tweaks
+ * (shot-dsl 0.5.0):
+ * - **A Brand Classic**: device frames on the vivid tonal brand palette; hero with the mascot + badge;
+ *   callouts on the selling screens (explicit, else from a tight `focus`); an accent rhythm (every 4th screen text-bottom); shadows.
+ * - **B Clean Frameless**: pale tonal backgrounds with dark text; big full-width frameless
+ *   screenshots bleeding deep off the bottom (a zoom card only where the plan marks an explicit
+ *   `crop`); magnified callouts (explicit, else derived from a tight `focus`); hero with large type
+ *   + the mascot.
+ * - **C Story Panorama**: the deep tonal palette as ONE continuous scene across triples/pairs of
+ *   screens with a flowing motif (`style.panorama.decoration`, default `wave`), the mascot
+ *   travelling across the seams, a tilted hero and deeper bleeds.
  *
  * KEPT from the input (every concept): name (+ suffix), canvas size, copy (headline / subheadline /
  * badge), colours (headlineColor / subheadlineColor), `background`, `deviceId`, `screenshot`,
- * `focus`, `crop`, and the style's `palette`, `font` and `bleed` preference (default `auto`).
+ * `focus`, `crop`, `callout`, per-screen `mascot`, `art`, and the style's `font` and `bleed`
+ * preference (default `auto`; B and C use `deep` unless the input says `none`).
+ *
+ * BRAND COLOURS: `style.palette.colors` (the first is the base, a tonal palette's second is the
+ * accent); without a palette, the first screen's background colour. Concepts then use
+ * `mode: "tonal"` with their own tone. Without any brand colour, the input palette/backgrounds stay.
  *
  * OVERRIDDEN (the concept decides these):
- * - every screen's `layout` → `text-top`: screens only share one device scale + baseline when they
- *   share a layout, and that shared system is what makes a set look designed;
- * - per-screen `presentation` / `tilt` are dropped; `style.presentation` is `device` (A, C) or
- *   `frameless` (B, with `zoom` on screens that have a `crop` or a focus band ≤ 45% tall);
- * - A and B are straight and without panorama (`tilt`, `tiltScreens`, `panorama` removed);
- * - C tilts screen 1 only (`tiltScreens: [0]`, the input's non-zero `style.tilt` or 8°) and uses the
- *   input's `panorama.spans` if it has them (else adjacent pairs of the same canvas size); its
- *   `straddle` is the input's if set, else the hero only; `decoration` defaults to `orbs`.
+ * - every screen's `layout` → `text-top` (one shared system; the hero and rhythm accents differ);
+ * - per-screen `presentation` / `tilt` are dropped;
+ * - `hero`, `rhythm`, `callouts`, `tilt`/`tiltScreens` and `panorama` are set per concept (C keeps the
+ *   input's `panorama.spans` / `decoration` when given).
  */
 export type VariantKey = 'A' | 'B' | 'C';
 
@@ -30,12 +46,12 @@ export interface ComposeVariant {
 	plan: ComposePlan;
 }
 
-export const VARIANT_LABELS: Record<VariantKey, string> = { A: 'Framed', B: 'Frameless', C: 'Panorama' };
+export const VARIANT_LABELS: Record<VariantKey, string> = { A: 'Brand Classic', B: 'Clean Frameless', C: 'Story Panorama' };
 
 /** Tilt (degrees) the panorama concept gives its hero screen. */
 export const VARIANT_HERO_TILT = 8;
-/** A focus band at most this tall (fraction of the screenshot) is worth a zoom card in concept B. */
-export const VARIANT_ZOOM_MAX_FOCUS = 0.45;
+/** Rhythm period of concept A (every 4th screen is an accent). */
+export const VARIANT_RHYTHM_EVERY = 4;
 
 const suffix = (name: string, key: VariantKey) => `${name} — ${key} ${VARIANT_LABELS[key]}`;
 
@@ -48,15 +64,65 @@ function baseScreen(screen: ComposeScreenPlan): ComposeScreenPlan {
 	return { ...copy, layout: 'text-top' };
 }
 
-function baseStyle(style: ComposeStyle | undefined): ComposeStyle {
+/** The plan's brand colours: [base, accent?] (see module doc), or null. */
+export function brandColors(plan: ComposePlan): { base: string; accent?: string } | null {
+	const pal = plan.style?.palette;
+	const colors = (pal?.colors ?? []).filter(isHexColor);
+	if (colors.length) return { base: colors[0], accent: pal?.mode === 'tonal' ? colors[1] : undefined };
+	const bg = plan.screens[0]?.background;
+	const first = bg?.type === 'gradient' ? (bg.gradient?.colorStops?.[0]?.color ?? bg.gradient?.colors?.[0]) : bg?.color;
+	return isHexColor(first) ? { base: first } : null;
+}
+
+function tonal(plan: ComposePlan, tone: 'light' | 'vivid' | 'deep'): ComposePalette | undefined {
+	const brand = brandColors(plan);
+	if (!brand) return plan.style?.palette ? JSON.parse(JSON.stringify(plan.style.palette)) : undefined;
+	return { mode: 'tonal', colors: brand.accent ? [brand.base, brand.accent] : [brand.base], tone };
+}
+
+function baseStyle(plan: ComposePlan): ComposeStyle {
+	const style = plan.style;
 	const out: ComposeStyle = { bleed: style?.bleed ?? 'auto' };
-	if (style?.palette) out.palette = JSON.parse(JSON.stringify(style.palette));
 	if (style?.font) out.font = style.font;
 	return out;
 }
 
+/** The hero mascot: the input hero's, else the first art, anchored by the headline. */
+function heroMascot(plan: ComposePlan, size?: number): ComposeMascot | undefined {
+	const given = plan.style?.hero && typeof plan.style.hero === 'object' ? plan.style.hero.mascot : undefined;
+	if (given) return { ...given };
+	const art = plan.art?.[0];
+	return art ? { art: art.id, anchor: 'headline', ...(size ? { size } : {}) } : undefined;
+}
+
+/** The input's hero screen index (-1 when the input turns the hero off). */
+function heroIndexOf(plan: ComposePlan): number {
+	const h = plan.style?.hero;
+	if (h === false) return -1;
+	const i = h && typeof h === 'object' && Number.isFinite(h.screen) ? Math.floor(h.screen!) : 0;
+	return Math.min(Math.max(0, i), Math.max(0, plan.screens.length - 1));
+}
+
+/** The concept's hero: the input's (incl. `screen`) + the concept's overrides; `false` stays off. */
+function hero(plan: ComposePlan, extra: ComposeHero, mascotSize?: number): ComposeHero | false {
+	if (plan.style?.hero === false) return false;
+	const input = plan.style?.hero && typeof plan.style.hero === 'object' ? plan.style.hero : {};
+	const out: ComposeHero = { ...JSON.parse(JSON.stringify(input)), ...extra };
+	const mascot = heroMascot(plan, mascotSize);
+	if (mascot) out.mascot = mascot;
+	return out;
+}
+
 /** Adjacent pairs [0,1], [2,3], … of screens that share a canvas size (a lone last screen stays single). */
 export function panoramaPairs(plan: ComposePlan): number[][] {
+	return panoramaRuns(plan, [2]);
+}
+
+/**
+ * Runs of adjacent same-canvas screens with lengths cycling through `sizes` (e.g. [3, 2] → triples
+ * and pairs), never leaving a lone screen when a shorter run fits.
+ */
+export function panoramaRuns(plan: ComposePlan, sizes: number[] = [3, 2]): number[][] {
 	const explicit = plan.canvasWidth != null || plan.canvasHeight != null;
 	const key = (s: ComposeScreenPlan) => {
 		if (explicit) return 'explicit';
@@ -64,57 +130,88 @@ export function panoramaPairs(plan: ComposePlan): number[][] {
 		return `${d.width}x${d.height}`;
 	};
 	const spans: number[][] = [];
-	for (let i = 0; i + 1 < plan.screens.length; ) {
-		if (key(plan.screens[i]) === key(plan.screens[i + 1])) {
-			spans.push([i, i + 1]);
-			i += 2;
-		} else {
-			i += 1;
-		}
+	let cycle = 0;
+	for (let i = 0; i < plan.screens.length; ) {
+		let len = 1;
+		while (i + len < plan.screens.length && key(plan.screens[i + len]) === key(plan.screens[i])) len++;
+		// `len` = same-canvas run from i; take the cycle's size, or the largest that fits.
+		let take = Math.min(sizes[cycle % sizes.length], len);
+		// Don't strand a single screen after this span when a smaller span would pair it up.
+		if (len - take === 1 && take > 2) take = 2;
+		if (take >= 2) {
+			spans.push(Array.from({ length: take }, (_, k) => i + k));
+			cycle++;
+			i += take;
+		} else i += 1;
 	}
 	return spans;
 }
 
 export function makeVariants(plan: ComposePlan): ComposeVariant[] {
-	const common = { canvasWidth: plan.canvasWidth, canvasHeight: plan.canvasHeight };
+	const common = { canvasWidth: plan.canvasWidth, canvasHeight: plan.canvasHeight, art: plan.art };
 	const strip = <T extends object>(o: T): T => JSON.parse(JSON.stringify(o)); // drops undefined keys
+	const badge = (plan.style?.hero && typeof plan.style.hero === 'object' ? plan.style.hero.badge : undefined) ?? undefined;
 
 	const a: ComposePlan = strip({
 		...common,
 		name: suffix(plan.name, 'A'),
-		style: { ...baseStyle(plan.style), presentation: 'device' },
+		style: {
+			...baseStyle(plan),
+			presentation: 'device',
+			palette: tonal(plan, 'vivid'),
+			hero: hero(plan, { badge }),
+			rhythm: { every: VARIANT_RHYTHM_EVERY, treatment: 'text-bottom' },
+			callouts: 'auto'
+		},
 		screens: plan.screens.map(baseScreen)
 	});
 
 	const b: ComposePlan = strip({
 		...common,
 		name: suffix(plan.name, 'B'),
-		style: { ...baseStyle(plan.style), presentation: 'frameless' },
+		style: {
+			...baseStyle(plan),
+			// Big screenshots bleeding decisively off the bottom: the editorial "clean" look.
+			bleed: plan.style?.bleed === 'none' ? 'none' : 'deep',
+			presentation: 'frameless',
+			palette: tonal(plan, 'light'),
+			hero: hero(plan, { badge, scale: 1.3 }),
+			callouts: 'auto'
+		},
 		screens: plan.screens.map((screen) => {
 			const s = baseScreen(screen);
-			const f = screen.focus;
-			const tight = !!f && Math.abs(f.bottom - f.top) <= VARIANT_ZOOM_MAX_FOCUS;
-			if (screen.crop || tight) s.presentation = 'zoom';
+			// B1: only an explicit `crop` becomes a zoom card; everything else shows the full screen.
+			if (screen.crop) s.presentation = 'zoom';
 			return s;
 		})
 	});
 
 	const pano = plan.style?.panorama;
-	const spans = pano?.spans?.length ? JSON.parse(JSON.stringify(pano.spans)) : panoramaPairs(plan);
-	const heroStraddle = spans.some((span: number[]) => span[0] === 0) ? [0] : [];
+	const spans: number[][] = pano?.spans?.length ? JSON.parse(JSON.stringify(pano.spans)) : panoramaRuns(plan);
+	const decoration: Motif = pano?.decoration && pano.decoration !== 'orbs' ? pano.decoration : 'wave';
+	const art = plan.art?.[0];
+	const heroIndex = heroIndexOf(plan);
 	const c: ComposePlan = strip({
 		...common,
 		name: suffix(plan.name, 'C'),
 		style: {
-			...baseStyle(plan.style),
+			...baseStyle(plan),
+			bleed: plan.style?.bleed === 'none' ? 'none' : 'deep',
 			presentation: 'device',
-			tilt: plan.style?.tilt ? plan.style.tilt : VARIANT_HERO_TILT,
-			tiltScreens: [0],
-			// Only the hero straddles by default (≤ 1 seam crossing per set); other spans keep the
-			// continuous background + orbs with centred, straight devices.
-			panorama: { spans, straddle: pano?.straddle ?? heroStraddle, decoration: pano?.decoration ?? 'orbs' }
+			palette: tonal(plan, 'deep'),
+			hero: hero(plan, { badge, tilt: plan.style?.tilt ? plan.style.tilt : VARIANT_HERO_TILT }, 0.26),
+			callouts: 'none',
+			// The continuous scene carries the story; a straddle only when the input asks for one
+			// (a straddle needs ≥ 18% of the device on the next screen, which a focus band rarely allows).
+			panorama: { spans, ...(pano?.straddle !== undefined ? { straddle: pano.straddle } : {}), decoration }
 		},
-		screens: plan.screens.map(baseScreen)
+		screens: plan.screens.map((screen, i) => {
+			const s = baseScreen(screen);
+			// The mascot travels: it crosses the first seam of every span except the hero's.
+			const span = spans.find((sp) => sp[0] === i);
+			if (art && span && !span.includes(heroIndex) && !s.mascot) s.mascot = { art: art.id, anchor: 'seam', size: 0.2 };
+			return s;
+		})
 	});
 
 	return [